docs: sync tool guide and components
This commit is contained in:
parent
2b75955c4f
commit
10b89f28ae
GPG Key ID:
13E498CE010AC6FD
@ -1,22 +1,23 @@
|
||||
# Project: Refactor AI Agent Tool Syntax to XML
|
||||
# AI Agent XML Tool Syntax
|
||||
|
||||
**Date:** 2025-05-31
|
||||
**Updated:** 2025-06-11
|
||||
|
||||
**Goal:** To refactor the AI agent's tool calling mechanism from a custom regex-parsed format to a standardized XML-based format. This aims to improve robustness, ease of AI generation, parsing simplicity, extensibility, and standardization.
|
||||
The AI agent defined in `cogs/ai_code_agent_cog.py` uses an XML-based format for all tool calls. When the agent needs to perform an action it responds **only** with an XML block. The name of the root element corresponds to the tool to invoke and the child elements provide the parameters.
|
||||
|
||||
**1. Current State:**
|
||||
The AI agent in `cogs/ai_code_agent_cog.py` uses a custom, line-based syntax for tool calls, defined in `AGENT_SYSTEM_PROMPT` and parsed using regular expressions in `_parse_and_execute_tool_call`.
|
||||
The following sections document the currently supported tools and their parameters.
|
||||
|
||||
**2. Proposed Change: XML-Based Tool Calls**
|
||||
|
||||
The AI will be instructed to output *only* an XML block when calling a tool. The root element of the XML block will be the tool's name.
|
||||
|
||||
**2.1. New XML Tool Call Syntax Definitions:**
|
||||
**Tool Call Syntax Examples:**
|
||||
|
||||
* **ReadFile:**
|
||||
```xml
|
||||
<ReadFile>
|
||||
<path>path/to/file.ext</path>
|
||||
<!-- Optional line range -->
|
||||
<start_line>10</start_line>
|
||||
<end_line>20</end_line>
|
||||
<!-- Optional peeking helpers -->
|
||||
<peek_first_n_lines>5</peek_first_n_lines>
|
||||
<peek_last_n_lines>5</peek_last_n_lines>
|
||||
</ReadFile>
|
||||
```
|
||||
|
||||
@ -59,7 +60,11 @@ The AI will be instructed to output *only* an XML block when calling a tool. The
|
||||
```xml
|
||||
<ListFiles>
|
||||
<path>path/to/search</path>
|
||||
<recursive>true</recursive> <!-- boolean: "true" or "false", defaults to false if tag omitted or value is not "true" -->
|
||||
<recursive>true</recursive> <!-- "true" or "false", defaults to false -->
|
||||
<!-- Optional filtering -->
|
||||
<filter_extensions>.py,.txt</filter_extensions>
|
||||
<filter_regex_name>test_.*\.py</filter_regex_name>
|
||||
<include_metadata>true</include_metadata>
|
||||
</ListFiles>
|
||||
```
|
||||
|
||||
@ -77,6 +82,102 @@ The AI will be instructed to output *only* an XML block when calling a tool. The
|
||||
</TaskComplete>
|
||||
```
|
||||
|
||||
* **LintFile:**
|
||||
```xml
|
||||
<LintFile>
|
||||
<path>path/to/python_file.py</path>
|
||||
<linter>pylint</linter>
|
||||
</LintFile>
|
||||
```
|
||||
|
||||
* **GetCodeStructure:**
|
||||
```xml
|
||||
<GetCodeStructure>
|
||||
<path>path/to/python_file.py</path>
|
||||
</GetCodeStructure>
|
||||
```
|
||||
|
||||
* **FindSymbolDefinition:**
|
||||
```xml
|
||||
<FindSymbolDefinition>
|
||||
<symbol_name>my_function</symbol_name>
|
||||
<search_path>./cogs</search_path>
|
||||
<file_pattern>*.py</file_pattern>
|
||||
</FindSymbolDefinition>
|
||||
```
|
||||
|
||||
* **ManageCog:**
|
||||
```xml
|
||||
<ManageCog>
|
||||
<action>reload</action>
|
||||
<cog_name>cogs.example_cog</cog_name>
|
||||
</ManageCog>
|
||||
```
|
||||
|
||||
* **RunTests:**
|
||||
```xml
|
||||
<RunTests>
|
||||
<test_path_or_pattern>tests/test_module.py</test_path_or_pattern>
|
||||
<framework>pytest</framework>
|
||||
</RunTests>
|
||||
```
|
||||
|
||||
* **PythonREPL:**
|
||||
```xml
|
||||
<PythonREPL>
|
||||
<code_snippet><![CDATA[
|
||||
print("Hello from REPL")
|
||||
]]></code_snippet>
|
||||
<session_id>optional_id</session_id>
|
||||
</PythonREPL>
|
||||
```
|
||||
|
||||
* **CreateNamedSnapshot:**
|
||||
```xml
|
||||
<CreateNamedSnapshot>
|
||||
<snapshot_name>feature_snapshot</snapshot_name>
|
||||
<description>Optional description</description>
|
||||
</CreateNamedSnapshot>
|
||||
```
|
||||
|
||||
* **CompareSnapshots:**
|
||||
```xml
|
||||
<CompareSnapshots>
|
||||
<base_ref>snapshot_a</base_ref>
|
||||
<compare_ref>snapshot_b</compare_ref>
|
||||
</CompareSnapshots>
|
||||
```
|
||||
|
||||
* **DryRunApplyDiff:**
|
||||
```xml
|
||||
<DryRunApplyDiff>
|
||||
<path>path/to/file.ext</path>
|
||||
<diff_block><![CDATA[
|
||||
[SEARCH_BLOCK_START]
|
||||
:start_line:10
|
||||
-------
|
||||
old line
|
||||
\=======
|
||||
new line
|
||||
[REPLACE_BLOCK_END]
|
||||
]]></diff_block>
|
||||
</DryRunApplyDiff>
|
||||
```
|
||||
|
||||
* **DryRunWriteFile:**
|
||||
```xml
|
||||
<DryRunWriteFile>
|
||||
<path>path/to/file.ext</path>
|
||||
</DryRunWriteFile>
|
||||
```
|
||||
|
||||
* **ReadWebPageRaw:**
|
||||
```xml
|
||||
<ReadWebPageRaw>
|
||||
<url>https://example.com/raw.txt</url>
|
||||
</ReadWebPageRaw>
|
||||
```
|
||||
|
||||
**3. Parsing Logic in `_parse_and_execute_tool_call` (Python):**
|
||||
|
||||
* The method will attempt to parse the `ai_response_text` as XML using `xml.etree.ElementTree`.
|
||||
@ -123,6 +224,17 @@ graph TD
|
||||
E -- ExecuteCommand --> I[Call _execute_tool_execute_command];
|
||||
E -- ListFiles --> J[Call _execute_tool_list_files];
|
||||
E -- WebSearch --> K[Call _execute_tool_web_search];
|
||||
E -- LintFile --> R[Call _execute_tool_lint_file];
|
||||
E -- GetCodeStructure --> S[Call _execute_tool_get_code_structure];
|
||||
E -- FindSymbolDefinition --> T[Call _execute_tool_find_symbol_definition];
|
||||
E -- ManageCog --> U[Call _execute_tool_manage_cog];
|
||||
E -- RunTests --> V[Call _execute_tool_run_tests];
|
||||
E -- PythonREPL --> W[Call _execute_tool_python_repl];
|
||||
E -- CreateNamedSnapshot --> X[Call _execute_tool_create_named_snapshot];
|
||||
E -- CompareSnapshots --> Y[Call _execute_tool_compare_snapshots];
|
||||
E -- DryRunApplyDiff --> Z[Call _execute_tool_dry_run_apply_diff];
|
||||
E -- DryRunWriteFile --> AA[Call _execute_tool_dry_run_write_file];
|
||||
E -- ReadWebPageRaw --> AB[Call _execute_tool_read_web_page_raw];
|
||||
E -- TaskComplete --> L[Process TaskComplete];
|
||||
E -- Unknown Tool --> M[Handle Unknown Tool / Error];
|
||||
B -- Invalid XML / Not a Tool --> N[Return "NO_TOOL" status];
|
||||
@ -132,7 +244,19 @@ graph TD
|
||||
I --> O;
|
||||
J --> O;
|
||||
K --> O;
|
||||
R --> O;
|
||||
S --> O;
|
||||
T --> O;
|
||||
U --> O;
|
||||
V --> O;
|
||||
W --> O;
|
||||
X --> O;
|
||||
Y --> O;
|
||||
Z --> O;
|
||||
AA --> O;
|
||||
AB --> O;
|
||||
L --> P[End Interaction];
|
||||
M --> P;
|
||||
N --> P;
|
||||
O --> Q[Add to History, Continue Loop];
|
||||
```
|
||||
|
||||
@ -299,7 +299,7 @@ class InfoView(discord.ui.LayoutView):
|
||||
|
||||
## See Also
|
||||
|
||||
More examples can be found in the
|
||||
`examples <examples>`{.interpreted-text role="resource"} directory.
|
||||
Refer to the `interactions/api`{.interpreted-text role="doc"} page for
|
||||
an exhaustive API reference.
|
||||
For additional usage examples, refer to the official `discord.py`
|
||||
documentation. This repository does not include the example suite from
|
||||
the library. See the `interactions/api` reference for an exhaustive API
|
||||
overview.
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user