> ## Documentation Index
> Fetch the complete documentation index at: https://docs.seekr.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent as tool

> Use agents as callable tools to build multi-agent workflows.

### What is an agent as tool?

An agent-as-tool lets a supervisor agent delegate subtasks to other agents. Instead of handing over control, the supervisor invokes a sub-agent as a callable tool, receives the result, and integrates it into a unified response. This enables composable, multi-agent systems where each agent focuses on a specific capability.

Use agent-as-tool when a task spans multiple intents or requires synthesis across specialized skills—for example, a research assistant that calls one sub-agent to fetch data and another to evaluate its relevance, then merges the results.

### How it works

<Steps>
  <Step>
    **Create sub-agents** – Build individual agents that each handle a specific capability.
  </Step>

  <Step>
    **Wrap each sub-agent as a tool** – Create an agent-as-tool that references the sub-agent's ID.
  </Step>

  <Step>
    **Attach the tools to a supervisor agent** – The supervisor uses the agent-as-tool like any other tool.
  </Step>

  <Step>
    **Run the supervisor** – The supervisor's planner decides when to invoke sub-agents based on the task and the tool descriptions you provide.
  </Step>
</Steps>

<Note>
  Sub-agents and their agent-as-tool wrappers must be created before the supervisor agent that uses them.
</Note>

## Create an agent as tool

First, create the sub-agent you want to expose as a tool. Then wrap it:

<CodeGroup>
  ```python Python theme={null}
  from seekrai import SeekrFlow
  from seekrai.types import CreateAgentAsTool, AgentAsToolConfig

  client = SeekrFlow()

  # Create the agent-as-tool
  agent_as_tool = client.tools.create(
      CreateAgentAsTool(
          name="research-agent-tool",
          description="Searches the web for current information on a given topic and returns a summary.",
          config=AgentAsToolConfig(
              agent_id="agent-abc123",
          ),
      )
  )

  print(f"Tool ID: {agent_as_tool.id}")
  ```
</CodeGroup>

### Parameters

| Parameter                       | Description                                                                                          |
| ------------------------------- | ---------------------------------------------------------------------------------------------------- |
| **name** (required)             | The name of the tool. Appears in spans and traces.                                                   |
| **type** (required)             | Must be `agent_as_tool`.                                                                             |
| **description** (required)      | Helps the supervisor agent decide when to invoke this tool. Included in the planner's system prompt. |
| **config.agent\_id** (required) | The ID of the sub-agent to run when this tool is invoked.                                            |

<Warning>
  Each agent can only have one agent-as-tool wrapper. Attempting to create a second agent-as-tool for the same sub-agent returns an error.
</Warning>

## Update an agent as tool

You can update the tool's name and description. The underlying sub-agent cannot be changed. To use a different sub-agent, create a new agent-as-tool for that sub-agent.

<CodeGroup>
  ```python Python theme={null}
  from seekrai.types import UpdateAgentAsTool

  updated_tool = client.tools.update(
      agent_as_tool.id,
      UpdateAgentAsTool(
          name="updated-research-tool",
          description="Updated description for the research sub-agent.",
      )
  )
  ```
</CodeGroup>

## Delete an agent as tool

Deleting an agent-as-tool removes the tool only. The underlying sub-agent is not affected.

<CodeGroup>
  ```python Python theme={null}
  client.tools.delete(agent_as_tool.id)
  ```
</CodeGroup>

<Note>
  An agent-as-tool cannot be deleted if it is still linked to a supervisor agent. Unlink it from the supervisor first.
</Note>

## Attach to a supervisor agent

Pass agent-as-tool IDs in the `tool_ids` parameter when creating or updating a supervisor agent. The syntax is the same as for any other tool type.

<CodeGroup>
  ```python Python theme={null}
  from seekrai.types import UpdateAgentRequest

  agent = client.agents.update(
      agent_id=supervisor.id,
      request=UpdateAgentRequest(
          name="Supervisor Agent",
          instructions="You are a research coordinator. Use your sub-agents to gather and analyze information.",
          model_id="meta-llama/Llama-3.3-70B-Instruct",
          reasoning_effort="performance_optimized",
          tool_ids=[agent_as_tool.id, web_search_tool.id],
      )
  )
  ```
</CodeGroup>

## Deployment behavior

When a supervisor agent is promoted, SeekrFlow automatically promotes any linked sub-agents that are not already active. The supervisor remains in `Pending` state until all sub-agents are ready.

When a supervisor is demoted, its sub-agents are **not** automatically demoted. You must demote each sub-agent individually if needed.

## Constraints

* **No cycles** — The agent graph must be a tree. Agent A cannot be a tool for Agent B if Agent B is already a tool for Agent A, directly or indirectly.
* **One tool per agent** — Each agent can only have one agent-as-tool wrapper. Duplicating an agent-as-tool is not supported.
* **Sub-agent deletion** — A sub-agent cannot be deleted while it is still linked to a supervisor. Unlink the agent-as-tool from the supervisor and delete the tool first.
* **Sub-agent demotion** — A sub-agent cannot be demoted while its supervisor is active. Either demote the supervisor first, or unlink the sub-agent.