Using Agents and Tools

TIP

More information on how agents and tools work and how you can create your own can be found in the Creating Tools guide.

As outlined by Andrew Ng in Agentic Design Patterns Part 3, Tool Use, LLMs can act as agents by leveraging external tools. Andrew notes some common examples such as web searching or code execution that have obvious benefits when using LLMs.

In the plugin, tools are simply context and actions that are shared with an LLM via a system prompt. The LLM and the chat buffer act as an agent by orchestrating their use within Neovim. Tools give LLM's knowledge and a defined schema which can be included in the response for the plugin to parse, execute and feedback on. Agents and tools can be added as a participant to the chat buffer by using the @ key.

IMPORTANT

The agentic use of some tools in the plugin results in you, the developer, acting as the human-in-the-loop and approving their use. I intend on making this easier in the coming releases

How Tools Work

LLMs are instructured by the plugin to return a structured XML block which has been defined for each tool. The chat buffer parses the LLMs response and detects any tool use before calling the appropriate tool. The chat buffer will then be updated with the outcome. Depending on the tool, flags may be inserted on the chat buffer for later processing.

@cmd_runner

The @cmd_runner tool enables an LLM to execute commands on your machine, subject to your authorization. A common example can be asking the LLM to run your test suite and provide feedback on any failures. Some commands do not write any data to stdout which means the plugin can't pass the output of the execution to the LLM. When this occurs, the tool will instead share the exit code.

The LLM is specifically instructed to detect if you're running a test suite, and if so, to insert a flag in its XML request. This is then detected and the outcome of the test is stored in the corresponding flag on the chat buffer. This makes it ideal for workflows to hook into.

An example of the XML that an LLM may generate for the tool:

<tools>
  <tool name="cmd_runner">
    <action>
      <command><![CDATA[make test]]></command>
      <flag>testing</flag>
    </action>
  </tool>
</tools>

@editor

The @editor tool enables an LLM to modify the code in a Neovim buffer. If a buffer's content has been shared with the LLM then the tool can be used to add, edit or delete specific lines. Consider pinning or watching a buffer to avoid manually re-sending a buffer's content to the LLM.

An example of the XML that an LLM may generate for the tool:

<tools>
  <tool name="editor">
    <action type="add">
      <code><![CDATA[
    def transfer(self, amount, account):
        pass
      ]]></code>
      <buffer>3</buffer>
      <line>15</line>
    </action>
    <action type="delete">
      <buffer>3</buffer>
      <start_line>17</start_line>
      <end_line>18</end_line>
    </action>
    <action type="update">
      <code><![CDATA[
    def deposit(self, amount):
        print(f"Depositing {amount}")
      ]]></code>
      <buffer>3</buffer>
      <start_line>11</start_line>
      <end_line>12</end_line>
    </action>
  </tool>
</tools>

@files

NOTE

All file operations require approval from the user before they're executed

The @files tool leverages the Plenary.Path module to enable an LLM to perform various file operations on the user's disk:

• Creating a file
• Reading a file
• Reading lines from a file
• Editing a file
• Deleting a file
• Renaming a file
• Copying a file
• Moving a file

An example of the XML that an LLM may generate for the tool:

<tools>
  <tool name="files">
    <action type="create">
      <contents><![CDATA[
<example>
  <title>Sample XML</title>
  <description>This is an example XML file for the files tool.</description>
  <items>
    <item>
      <name>Item 1</name>
      <value>Value 1</value>
    </item>
    <item>
      <name>Item 2</name>
      <value>Value 2</value>
    </item>
  </items>
</example>
      ]]></contents>
      <path>/Users/Oli/Code/Python/benchmarking/exercises/practice/bank-account/example.xml</path>
    </action>
  </tool>
</tools>

@rag

The @rag tool uses jina.ai to parse a given URL's content and convert it into plain text before sharing with the LLM. It also gives the LLM the ability to search the internet for information.

@full_stack_dev

The @full_stack_dev agent is a combination of the @cmd_runner, @editor and @files tools.

Useful Tips

Automatic Tool Mode

The plugin allows you to run tools on autopilot. This automatically approves any tool use instead of prompting the user, disables any diffs, and automatically saves any buffers that the agent has edited. Simply set the global variable vim.g.codecompanion_auto_tool_mode to enable this or set it to nil to undo this. Alternatively, the keymap gta will toggle the feature whist from the chat buffer.