> ## Documentation Index > Fetch the complete documentation index at: https://docs.asteragents.com/llms.txt > Use this file to discover all available pages before exploring further. # Manage Agents Tool > List, create, and update agents in your organization — from within an agent conversation ## 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](/tools/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](#value--roi-optional) (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](/features/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: ```json theme={null} // 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 ```json theme={null} { "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 ```json theme={null} { "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 ## Related tools * [Call Agent](/tools/call_agent) - Call other agents after discovering them with `manage_agents` * [Schedule Task](/tools/schedule_task) - Schedule recurring tasks on agents you've created * [Load Skill](/tools/load_skill) - Load specialized skills into agents