Manage Agents Tool

What it does

The Manage Agents tool gives agents awareness of the other agents in their organization. Agents can list all available agents, create new ones, and update existing configurations — all through a single tool with an action parameter. This is especially powerful when paired with Call Agent: an agent can discover what’s available, then make an informed decision about which agent to delegate to.

Key features

Discover agents: List all agents in the org with their names, IDs, descriptions, tools, tags, and stage
Create agents: Build new agents with a name, system prompt, model, and tools — no UI needed
Update agents: Modify an existing agent’s description, system prompt, model, tools, or stage
Self-awareness: The calling agent is marked with isCurrentAgent: true in list results

Parameters

Parameter	Type	Required	Description
`action`	string	Yes	`"list"`, `"get"`, `"create"`, `"update"`, `"list_tags"`, `"rename_tag"`, or `"delete_tag"`
`name`	string	No	Filter for `list` — case-insensitive regex match on agent name
`stage`	string	No	Filter for `list`, or set stage on `update`. Values: `"development"` or `"released"`
`targetAgentId`	integer	For `get` / `update`	The ID of the agent to read or update
`agentName`	string	For `create`	Name of the new agent
`description`	string	No	Agent description (for `create` / `update`)
`systemPrompt`	string	No	System prompt / instructions (for `create` / `update`)
`model`	string	No	Model ID in `provider:model-id` format, e.g. `"anthropic:claude-sonnet-4-6"` (for `create` / `update`)
`toolNames`	string[]	No	Array of tool names to assign, e.g. `["search_google", "scrape_url"]` (for `create` / `update`)
`conversationStarters`	string[]	No	Suggested prompts shown as clickable chips in the chat dropdown. Without them the dropdown shows generic placeholders. On `update`, the array replaces the existing starters
`accessibleKnowledgeBaseIds`	integer[]	No	Knowledge bases this agent can read. Setting it automatically adds `search_knowledge_base` and points it at these KBs — no separate UI step. Replaces the prior set; pass `[]` to unlink all
`writableKnowledgeBaseIds`	integer[]	No	Knowledge bases this agent can write to. Setting it automatically adds `write_to_knowledge_base` and points it at these KBs. Replaces the prior set; pass `[]` to unlink all
`dataStoreIds`	integer[]	No	Data stores (structured KBs) this agent can query, write, and manage. Setting it automatically adds the `query_data_store`, `write_data_store`, and `manage_data_store` tools pointed at these stores. Replaces the prior set
`showInChat`	boolean	No	Whether the agent appears in the chat dropdown. New agents default to `false` (hidden) so development-stage agents don’t clutter the dropdown — pass `true` to surface one immediately, or flip it on `update`
`valueRule`	object \| null	No	Optional. What one unit of this agent’s work is worth, for value/ROI tracking. Pass `null` to clear it. Most agents leave this unset. See Value & ROI (for `create` / `update`)
`versionLabel`	string	No	Optional note recorded on the config version this `create` / `update` produces, shown in the agent’s version history. Accepted by the API (`POST /agents`) but not currently exposed in the tool schema, so agents can’t set it from chat yet
`tags`	string[]	No	Tag names for the agent (for `create` / `update`). Names are created in the org if new and matched case-insensitively to existing ones, so `"deal flow"` reuses `"Deal Flow"`. Replaces the agent’s existing tags; pass `[]` to clear. Tags are how people browse agents — tag every agent you create, and reuse the org’s existing names rather than inventing near-duplicates
`includeUsage`	boolean	No	For `list`: attach each agent’s conversation count, token counts, estimated cost, and `lastUsedAt` over a trailing window. Slower on large orgs, so omit it when you only need names and IDs
`usageDays`	integer	No	For `list` with `includeUsage`: the trailing window in days. Default `30`, max `365`
`tagId`	integer	For `rename_tag` / `delete_tag`	The tag to rename or delete. Get IDs from `list_tags`
`tagName`	string	For `rename_tag`	The new name
`expectedAgentCount`	integer	For `delete_tag`	How many agents currently carry the tag, from `list_tags`. Deleting a tag untags all of them, so the count must match or the delete is refused

The model field uses the provider:model-id format — bare names like "claude-sonnet-4-6" or date-stamped Anthropic API IDs like "claude-sonnet-4-20250514" are rejected. See Choosing a Model > Model Identifiers for the full list of accepted strings.

Common use cases

Agent discovery for call_agent

“What agents are available in our org that I could delegate research tasks to?” The agent lists all agents, inspects their tools and descriptions, and recommends the best fit before calling it.

Dynamic agent creation

“Create a new agent called ‘Daily Digest Bot’ that uses search_google and send_email to compile daily news summaries” The agent creates a fully configured agent — ready to use immediately in development stage.

Updating agent configuration

“Add the execute_python tool to agent 42 and update its description” The agent updates the target agent’s tools and metadata. Existing tool configs (like callable agent IDs) are preserved when tools are updated.

Organizing agents with tags

“Review the agents in this org and group them by team and function” The agent lists every agent with includeUsage: true to see what’s actually used, checks list_tags for names that already exist, then sets tags on each agent. Those tags become the categories people browse in the agent picker and in Control Hub → Agents. rename_tag and delete_tag let it tidy up afterwards — a delete has to state how many agents it will untag, so a stale view of the org can’t wipe associations by accident.

Self-replicating workflows

An orchestrator agent can create specialized sub-agents on the fly, configure them with the right tools and prompts, then call them via call_agent — all in a single conversation.

Value & ROI (optional)

The optional valueRule field quantifies what an agent’s work is worth, so the platform can show estimated value and ROI next to the cost it already computes for every run. It’s entirely optional — most agents leave it unset, and when it’s unset no value or ROI is shown (never a misleading $0). The rule has two trigger types:

// Every conversation this agent has is worth $25
{ "trigger": "run", "amountUsd": 25 }

// Worth $50 each time the agent sends an email
{ "trigger": "tool", "toolName": "send_email", "amountUsd": 50, "countPer": "call" }

Field	Description
`trigger`	`"run"` (any conversation) or `"tool"` (a specific tool is used)
`amountUsd`	Dollar value — must be greater than `0` (a `$0` rule is rejected, not stored)
`toolName`	Required for `trigger: "tool"` — must be one of the agent’s own tools
`countPer`	For `trigger: "tool"`: `"thread"` counts once per conversation the tool fired (default), `"call"` counts each invocation

Pass valueRule: null on update to remove a rule. Value shows up per-conversation in the Inbox and rolls up (with ROI) on the Analytics dashboard.

How tool assignment works

When creating or updating agents, pass tool names as simple strings in the toolNames array. The platform automatically:

Resolves each name to its full schema definition
Adds companion tools (e.g., search_knowledge_base automatically adds read_file and list_kb_files)
Preserves existing tool-specific configs (like callableAgentIds) on update
Validates tool names and returns an error for any unrecognized tools

What you get back

List response

{
  "status": "success",
  "content": {
    "totalAgents": 12,
    "agents": [
      {
        "id": 38,
        "name": "Research Assistant",
        "description": "General-purpose research agent",
        "model": "anthropic:claude-sonnet-4-6",
        "stage": "released",
        "tools": ["search_google", "scrape_url", "ask_web"],
        "tags": [{"id": 2, "name": "Research"}],
        "isCurrentAgent": true
      }
    ]
  }
}

Usage (with `includeUsage`)

Each agent in the list response gains a usage object for the window. Agents with no activity get zeros rather than being omitted — “never used” is exactly the signal a cleanup pass is looking for.

"usage": {
  "assistantMessages": 212,
  "inputTokens": 30120455,
  "outputTokens": 487930,
  "cachedInputTokens": 24770012,
  "cacheWriteTokens": 1102344,
  "totalTokens": 30608385,
  "estimatedCostUsd": 74.66,
  "unpricedModels": [],
  "lastUsedAt": "2026-08-21T22:55:43.337Z"
}

Cost is an estimate from list prices (with cache reads and writes priced at their own rates), not billed spend. It comes back null — not 0 — when some tokens ran on a model with no pricing entry, and unpricedModels names which.

Tag responses

list_tags returns { totalTags, tags: [{ id, name, agentCount }] }. rename_tag returns the tag with its previousName; renaming onto a name another tag already uses is refused with that tag’s ID so you can merge instead. delete_tag returns { id, name, untaggedAgents }.

Create / Update response

{
  "status": "success",
  "content": {
    "id": 510,
    "name": "Daily Digest Bot",
    "description": "Compiles daily news summaries",
    "model": "anthropic:claude-sonnet-4-6",
    "stage": "development",
    "tools": ["search_google", "send_email"],
    "valueRule": { "trigger": "tool", "toolName": "send_email", "amountUsd": 50, "countPer": "call" },
    "message": "Agent \"Daily Digest Bot\" created successfully (ID: 510)"
  }
}

Best practices

List before you call: Use action: "list" to discover agent names and IDs before using call_agent, rather than guessing
New agents start in development: Created agents always start in development stage — promote to released via update when ready
Tool names from existing agents: If you’re unsure which tool names are valid, list an existing agent to see its tool names
Preserve tool configs on update: When updating tools, the platform preserves existing configs (like callableAgentIds) for tools that remain in the set

Call Agent - Call other agents after discovering them with manage_agents
Manage Scheduled Tasks - Schedule recurring tasks on agents you’ve created
Load Skill - Load specialized skills into agents

Get Started

Agents & Features

Organization Settings

Integrations

Tools Reference

Advanced

What it does

Key features

Parameters

Common use cases

Agent discovery for call_agent

Dynamic agent creation

Updating agent configuration

Organizing agents with tags

Self-replicating workflows

Value & ROI (optional)

How tool assignment works

What you get back

List response

Usage (with `includeUsage`)

Tag responses

Create / Update response

Best practices

​What it does

​Key features

​Parameters

​Common use cases

​Agent discovery for call_agent

​Dynamic agent creation

​Updating agent configuration

​Organizing agents with tags

​Self-replicating workflows

​Value & ROI (optional)

​How tool assignment works

​What you get back

​List response

​Usage (with includeUsage)

​Tag responses

​Create / Update response

​Best practices

​Related tools

What it does

Key features

Parameters

Common use cases

Agent discovery for call_agent

Dynamic agent creation

Updating agent configuration

Organizing agents with tags

Self-replicating workflows

Value & ROI (optional)

How tool assignment works

What you get back

List response

Usage (with `includeUsage`)

Tag responses

Create / Update response

Best practices

Related tools