Skip to main content

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

ParameterDescription
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.
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. To use a different sub-agent, create a new agent-as-tool for that sub-agent. 
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.",
    )
)

​
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)
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,
    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],
    )
)

​
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.
Last modified on June 23, 2026