> ## 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"`, `"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](/features/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](#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. 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](/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. ### 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: ```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 } ] } } ``` ### 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. ```json theme={null} "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 ```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` * [Manage Scheduled Tasks](/tools/manage_scheduled_tasks) - Schedule recurring tasks on agents you've created * [Load Skill](/tools/load_skill) - Load specialized skills into agents