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

1. Create sub-agents — Build individual agents that each handle a specific capability.
2. Wrap each sub-agent as a tool — Create an agent-as-tool that references the sub-agent's ID.
3. Attach the tools to a supervisor agent — The supervisor uses the agent-as-tool like any other tool.
4. Run the supervisor — The supervisor's planner decides when to invoke sub-agents based on the task and the tool descriptions you provide.

ℹ️

Note

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

Create an agent as tool

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

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}")

Parameters

❗

Important

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.

Update an agent as tool

You can update the tool's name and description. The underlying sub-agent cannot be changed—if you need a different sub-agent, delete this tool and create a new one.

from seekrai.types import UpdateAgentAsTool, AgentAsToolConfig

updated_tool = client.tools.update(
    agent_as_tool.id,
    UpdateAgentAsTool(
        name="updated-research-tool",
        description="Updated description for the research sub-agent.",
        config=AgentAsToolConfig(
            agent_id="agent-abc123",  # Must match the original agent ID
        ),
    )
)

❗

Important

Updates require the full tool object—the SDK does not support partial updates. Include all fields, even those you are not changing, or they will be set to null.

Delete an agent as tool

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

client.tools.delete(agent_as_tool.id)

ℹ️

Note

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

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.

from seekrai.types import UpdateAgentRequest

agent = client.agents.update(
    agent_id=supervisor.id,
    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],
    )
)

Promotion 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.