Skip to main content
Build Agent

Agent Tool Configuration

Tools define what an Agent can do. By configuring the tools field when creating or updating an Agent, you can precisely control the boundaries of the Agent's capabilities.

The Role of Tools

When executing tasks, an Agent decides which capabilities it can invoke based on the tools configuration. All tools are configured through a single object { "type": "agent_toolset_20260401", "enabled_tools": [...] }, enabling the atomic tools listed in the enabled_tools array as needed. When enabled_tools is a non-empty allowlist, tools outside the list are completely invisible at the model layer and no invocation attempts will occur. When enabled_tools is omitted or is an empty array, all built-in tools are exposed to the model. When the entire tools field is omitted or written as [], the model layer receives no tool schema at all (see the FAQ below for details).

Available Tools

Tool Name (value in enabled_tools array)PurposeTypical Scenarios
BashShell command executionInstall dependencies, run scripts, curl API calls
ReadFile readView mounted files, code reading
WriteFile write (create/overwrite)Generate reports, produce artifacts
EditPartial file editModify configuration, modify code
GlobWildcard file listingFind code files
GrepFile content searchLocate strings
WebFetchHTTP GET for a single pageFetch documents/pages
WebSearchOnline searchRetrieve information
DeliverArtifactsSystem-reserved tool, part of the "all enabled" set (when enabled_tools is omitted or empty)Not recommended to explicitly declare in enabled_tools
Notes:
  • Tool names are capitalized (Bash, not bash); the event stream also uses the capitalized form
  • Omitting enabled_tools or setting it to an empty array [] is equivalent to enabling all built-in tools (including DeliverArtifacts in the table above); if you want the Agent to have no tools at all, omit the entire tools field or set it to []
  • Each tool name in enabled_tools is validated—entering an unknown name (such as "Foo") will return a 400 error: "unknown tool name 'Foo'"
  • The old per-tool object schema (such as {"type": "bash_20250124"}) is no longer supported

Current Format: Single Object

Tool configuration uses a single object, with specific tools toggled via the enabled_tools array: 
{
  "tools": [
    {
      "type": "agent_toolset_20260401",
      "enabled_tools": ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "WebFetch", "WebSearch"]
    }
  ]
}
Set when creating an Agent: 
curl -X POST https://api.qoder.com.cn/api/v1/cloud/agents \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "dev-agent",
    "model": "ultimate",
    "instructions": "You are a development assistant",
    "tools": [
      {
        "type": "agent_toolset_20260401",
        "enabled_tools": ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "WebFetch", "WebSearch"]
      }
    ]
  }'

Tool Configuration Examples

Minimal Configuration (Command Line Only)

{
  "tools": [
    {
      "type": "agent_toolset_20260401",
      "enabled_tools": ["Bash"]
    }
  ]
}

Full Development Environment

{
  "tools": [
    {
      "type": "agent_toolset_20260401",
      "enabled_tools": ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "WebFetch", "WebSearch"]
    }
  ]
}

Create a New Version (PUT Full Replacement)

Create a new version of an Agent via PUT to update the tool configuration: 
curl -X PUT https://api.qoder.com.cn/api/v1/cloud/agents/agent_abc123 \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "version": 1,
    "tools": [
      {
        "type": "agent_toolset_20260401",
        "enabled_tools": ["Bash", "Read", "Write", "Edit"]
      }
    ]
  }'
PUT is a full replacement (not a patch); fields not included will be cleared. You must include the version field for optimistic concurrency control:
  • Included version equals the current version → 200, version + 1
  • Included version is outdated → 409 { error: { type: "conflict_error", message: "Version conflict. Expected version N, got M." }}
Existing Sessions are not affected; new Sessions use the updated configuration.

curl to View the Current Tool Configuration

curl https://api.qoder.com.cn/api/v1/cloud/agents/agent_abc123 \
  -H "Authorization: Bearer $QODER_PAT" | jq '.tools'
Example output: 
[
  {
    "type": "agent_toolset_20260401",
    "enabled_tools": ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "WebFetch", "WebSearch"]
  }
]

FAQ

Q: What happens if I do not configure tools? A: The Agent will have no tools available and can only engage in plain-text conversation. To give the Agent tool capabilities, at minimum pass [{"type":"agent_toolset_20260401"}] (equivalent to enabling all built-in tools). Q: Can tool configuration be overridden at the Session level? A: Not currently supported. Tool configuration is bound to the Agent; all Sessions of the same Agent share the same toolset. Q: Does the order of the tools array matter? A: No. The Agent autonomously decides which tool to invoke based on the task context. Q: Will the version suffix change over time? A: Yes. When the API releases a new version of tools, a new date suffix will be provided. We recommend watching the Changelog to select the latest version.
Guides
Tutorials
API Reference