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"`, `"create"`, or `"update"`
`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 `update`	The ID of the agent to 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`)
`showInChat`	boolean	No	Whether the agent appears in the chat dropdown. Defaults to `true`
`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

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.

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
      }
    ]
  }
}

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
Schedule Task - 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

Self-replicating workflows

Value & ROI (optional)

How tool assignment works

What you get back

List response

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

​Self-replicating workflows

​Value & ROI (optional)

​How tool assignment works

​What you get back

​List response

​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

Self-replicating workflows

Value & ROI (optional)

How tool assignment works

What you get back

List response

Create / Update response

Best practices

Related tools