Agent as tool

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

Create sub-agents – Create an agent for each specific capability, and note its agent ID.

Wrap each sub-agent as a tool – Create an agent-as-tool that references the sub-agent’s ID.

Attach the tools to a supervisor agent – The supervisor uses the agent-as-tool like any other tool.

Run the supervisor – The supervisor 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 and note its agent ID. 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

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 supervisor’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="high",
        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.

​What is an agent as tool?

​How it works

​Create an agent as tool

​Parameters

​Update an agent as tool

​Delete an agent as tool

​Attach to a supervisor agent

​Deployment behavior

​Constraints

What is an agent as tool?

How it works

Create an agent as tool

Parameters

Update an agent as tool

Delete an agent as tool

Attach to a supervisor agent

Deployment behavior

Constraints