Agentic Architectures

Catalogue / Tools & Action

Tool Use

The agent calls a tool, reads the result, and decides again

Shape
loop
Model calls
1 + tool rounds (typically 2 to 5)
Latency
low
Complexity
low

Also known as Function calling, Act-and-observe loop

1

How does an agent get facts and actions it cannot produce from memory?

A model only knows what it was trained on and can only write text. Tool use gives it a short list of functions, such as a database lookup or a pricing API. Each round it either calls one and reads the result, or gives its final answer.

You may need it if

  • Answers need live data, such as a customer's plan, an order status or today's price.
  • The model guesses numbers that a single query or calculation would get right.
  • Staff copy data from one system into the chat before asking the question.
2

When are tools the wrong answer?

Use it when

  • The answer depends on data held in your systems, not in the model.
  • A few well-defined functions cover what the agent needs, ideally fewer than ten.
  • Each call is cheap to run and its result is short enough to read.

Avoid it when

  • The task needs many dependent steps and the agent loses track of why it made each call.
    Use ReAct instead
  • Some calls change records, send messages or spend money, and a wrong one is costly.
    Use Dry Run instead
  • The work is a long, known sequence of steps that should be laid out before anything runs.
    Use Planning instead
  • The answer needs reading and judging many documents, not calling a function.
    Use Agentic RAG instead

What it costs

Model calls
1 + tool rounds (typically 2 to 5)
Latency
low
Complexity
low
3

How does a request turn into tool calls and an answer?

A tight loop. The agent replies with either a tool call or a final answer. A call is checked, run by the harness, and its result goes back to the agent. A round limit ends the loop even if the agent keeps asking.

tool callallowed,roundsleftrejected withthe reasontool resultfinal answerround limitreachedTask: The request or question, plus the list of tools the agent may call.TaskAgent: Reads the task and past results, then writes either one tool call or the final answer.AgentCall allowed?: Checks the call names a listed tool with sensible arguments, and counts the rounds used.Call allowed?Tools: Your functions, run by the harness with your credentials. Returns a short result or an error.ToolsAnswer: The final reply, with the calls made and their results.Answer
  1. Step 1 of 5

    The agent decides what it needs

    The agent reads the task, for example "Is customer 812 eligible for a refund?". It knows it needs the order history, so it writes a call to the order lookup tool.

  2. Step 2 of 5

    The call is checked

    Before anything runs, plain code checks the tool exists, the arguments make sense and rounds remain. A bad call goes back to the agent with the reason instead of failing silently.

  3. Step 3 of 5

    The harness runs the tool

    Your code runs the function and returns the result, trimmed to what matters. The agent never holds the credentials; it only sees what comes back.

  4. Step 4 of 5

    The result comes back

    The agent reads the result and decides again. It may call another tool, such as the refund policy lookup, or it may now have enough to answer.

  5. Step 5 of 5

    The agent answers, or time runs out

    A final answer leaves with the record of calls made. If the round limit is hit first, the run ends anyway and the answer says it is incomplete.

What each part does
Task
The request or question, plus the list of tools the agent may call.
Agent
Reads the task and past results, then writes either one tool call or the final answer.
Call allowed?
Checks the call names a listed tool with sensible arguments, and counts the rounds used.
Tools
Your functions, run by the harness with your credentials. Returns a short result or an error.
Answer
The final reply, with the calls made and their results.
  • Agent → Call allowed?: tool call
  • Call allowed? → Tools: allowed, rounds left
  • Call allowed? → Agent: rejected with the reason
  • Tools → Agent: tool result
  • Agent → Answer: final answer
  • Call allowed? → Answer: round limit reached

Where it connects

Entry
task
TaskQuestion

A request or question that one agent can handle with the listed tools. The tool list and any limits on their use come with it.

Exit
answer
AnswerOutcome

When: The agent gives a final answer, or the round limit is reached.

The final reply, the list of tool calls with their results, and a flag saying whether the round limit cut the run short.

4

What do I ask my assistant to set up?

The agents to launch

Tool agent

Answer the task using the listed tools. Each turn, either call exactly one tool with complete arguments, or give your final answer. Do not guess a fact a tool can give you. When you answer, list the calls you relied on.

Sees: The task, the tool descriptions, and every call and result so far. Not the credentials or raw tool internals.

Call checker

Check one proposed tool call. Reject it if the tool is not on the list, an argument is missing or malformed, or it repeats an earlier call with the same arguments. Give a one-line reason. Do not judge whether the task is solved.

Sees: The tool list with argument rules, the proposed call and the previous calls. Not the agent's conversation.

A prompt you can paste

Works with any assistant that can launch sub-agents. It contains the agents, the procedure and the stop rule above.

Framework-agnostic prompt
You are the orchestrator of a multi-agent workflow that follows the "Tool Use" architecture.
Launch every agent listed below as a separate sub-agent with its own context. Give each agent only the context stated for it. Do not do an agent's work yourself. If you cannot launch sub-agents, play each agent in a clearly separated turn and never let it use what is withheld from it.

# Task
[Describe your task here]

# Tool Use
The agent calls a tool, reads the result, and decides again.
Input: the task above. It must provide: A request or question that one agent can handle with the listed tools. The tool list and any limits on their use come with it. If something essential is missing, ask for it before starting.

Agents to launch:
- Tool agent: Answer the task using the listed tools. Each turn, either call exactly one tool with complete arguments, or give your final answer. Do not guess a fact a tool can give you. When you answer, list the calls you relied on.
  Context for this agent: The task, the tool descriptions, and every call and result so far. Not the credentials or raw tool internals.
- Call checker: Check one proposed tool call. Reject it if the tool is not on the list, an argument is missing or malformed, or it repeats an earlier call with the same arguments. Give a one-line reason. Do not judge whether the task is solved.
  Context for this agent: The tool list with argument rules, the proposed call and the previous calls. Not the agent's conversation.

Procedure:
1. List the tools the job needs, at most ten, each with a one-line description, its arguments and an example.
2. Make every tool return a short result. Cap long outputs and say how many items were left out.
3. Launch the tool agent on the task with the tool list.
4. For each tool call, launch the call checker. If it rejects, return the reason to the agent. If it allows, run the tool and return the result.
5. Count rounds. After 6 tool calls, stop running tools and ask the agent for its best final answer with what it has.

Stop rule: Stop when the agent gives a final answer, or after 6 tool calls, whichever comes first. At the limit, ask once for a final answer and mark it incomplete.

Exit:
- `answer`, when: The agent gives a final answer, or the round limit is reached. Deliver: The final reply, the list of tool calls with their results, and a flag saying whether the round limit cut the run short.

# Final deliverable
The final answer, then each tool call with its arguments and a one-line summary of its result, and whether the round limit was reached.

The same thing in code

LangGraph, python, package langgraph
import operator
from typing import Annotated, TypedDict

from langchain.chat_models import init_chat_model
from langchain_core.messages import AIMessage, AnyMessage, HumanMessage, SystemMessage, ToolCall, ToolMessage
from langchain_core.tools import tool
from langgraph.graph import END, START, StateGraph
from langgraph.graph.message import add_messages
from pydantic import BaseModel

MAX_CALLS = 6


@tool
def search_docs(query: str) -> str:
    """Search the product docs and return the top 3 matches. Example: search_docs(query="refund policy")"""
    return "stub: 3 matches"  # plug in your search index; cap the output


@tool
def get_order(order_id: str) -> str:
    """Fetch one order by id. Example: get_order(order_id="A-1042")"""
    return "stub: order summary"  # plug in your database, read-only


TOOLS = {t.name: t for t in (search_docs, get_order)}
TOOL_RULES = "\n".join(f"- {t.name} {t.args}: {t.description}" for t in TOOLS.values())
AGENT = ("Answer the task using the listed tools. Each turn, call exactly one tool with complete "
         "arguments, or give your final answer. Do not guess a fact a tool can give you.")
CHECKER = ("Check one proposed tool call. Reject it if the tool is not listed, an argument is missing "
           "or malformed, or it repeats an earlier call. Give a one-line reason.")


class Verdict(BaseModel):
    allowed: bool
    reason: str


class State(TypedDict):
    messages: Annotated[list[AnyMessage], add_messages]
    log: Annotated[list[str], operator.add]
    approved: list[ToolCall]
    limit_hit: bool


model = init_chat_model("anthropic:claude-sonnet-5-5")
agent_model = model.bind_tools(list(TOOLS.values()))
checker_model = model.with_structured_output(Verdict)


def last_ai(state: State) -> AIMessage:
    msg = state["messages"][-1]
    assert isinstance(msg, AIMessage)
    return msg


async def agent(state: State) -> dict:
    return {"messages": [await agent_model.ainvoke([SystemMessage(AGENT), *state["messages"]])]}


async def check(state: State) -> dict:
    calls = last_ai(state).tool_calls
    if len(state["log"]) + len(calls) > MAX_CALLS:  # the gate: at most 6 tool calls
        return {"limit_hit": True, "approved": []}
    approved, rejected = [], []
    for call in calls:
        # the checker sees the tool rules and the calls, not the agent's conversation
        prompt = f"Tools:\n{TOOL_RULES}\n\nProposed: {call['name']} {call['args']}\n\nPrevious:\n" + "\n".join(state["log"])
        verdict = Verdict.model_validate(await checker_model.ainvoke([SystemMessage(CHECKER), HumanMessage(prompt)]))
        if verdict.allowed:
            approved.append(call)
        else:
            rejected.append(ToolMessage(f"Rejected: {verdict.reason}", tool_call_id=call["id"] or ""))
    return {"approved": approved, "messages": rejected}


async def tools(state: State) -> dict:
    results, log = [], []
    for call in state["approved"]:
        output = str(await TOOLS[call["name"]].ainvoke(call["args"]))
        results.append(ToolMessage(output, tool_call_id=call["id"] or ""))
        log.append(f"{call['name']} {call['args']} -> {output[:120]}")
    return {"messages": results, "log": log}


async def final(state: State) -> dict:
    skipped = [ToolMessage("Not run: round limit reached.", tool_call_id=c["id"] or "") for c in last_ai(state).tool_calls]
    nudge = HumanMessage("Round limit reached. Give your best final answer now with what you have.")
    reply = await agent_model.ainvoke([SystemMessage(AGENT), *state["messages"], *skipped, nudge])
    return {"messages": [*skipped, nudge, reply]}


def after_check(state: State) -> str:
    return "final" if state["limit_hit"] else "tools" if state["approved"] else "agent"


builder = StateGraph(State)
for name, node in {"agent": agent, "check": check, "tools": tools, "final": final}.items():
    builder.add_node(name, node)
builder.add_edge(START, "agent")
builder.add_conditional_edges("agent", lambda s: "check" if last_ai(s).tool_calls else END, ["check", END])
builder.add_conditional_edges("check", after_check, ["tools", "agent", "final"])
builder.add_edge("tools", "agent")
builder.add_edge("final", END)
graph = builder.compile()


async def run(task: str) -> dict:
    state = await graph.ainvoke(
        {"messages": [HumanMessage(task)], "log": [], "approved": [], "limit_hit": False},
        {"recursion_limit": 40},
    )
    return {"answer": state["messages"][-1].text, "calls": state["log"], "incomplete": state["limit_hit"]}

Replace the two stubs with your real read-only tools, cap what each returns, and keep write tools out of this loop unless they get their own gate.

Claude Agent SDK, python, package claude-agent-sdk
from typing import Any

from claude_agent_sdk import (
    AgentDefinition, ClaudeAgentOptions, PermissionResultAllow, PermissionResultDeny,
    ResultMessage, ToolPermissionContext, create_sdk_mcp_server, query, tool,
)
from pydantic import BaseModel

MAX_CALLS = 6


@tool("search_docs", 'Search the product docs, top 3 matches. Example: {"query": "refund policy"}', {"query": str})
async def search_docs(args: dict[str, Any]) -> dict[str, Any]:
    return {"content": [{"type": "text", "text": "stub: 3 matches"}]}  # plug in your search index


@tool("get_order", 'Fetch one order by id. Example: {"order_id": "A-1042"}', {"order_id": str})
async def get_order(args: dict[str, Any]) -> dict[str, Any]:
    return {"content": [{"type": "text", "text": "stub: order summary"}]}  # plug in your database, read-only


SERVER = create_sdk_mcp_server("tools", tools=[search_docs, get_order])
TOOL_NAMES = ["mcp__tools__search_docs", "mcp__tools__get_order"]
TOOL_RULES = "search_docs(query: str): search the docs\nget_order(order_id: str): fetch one order"

AGENTS = {
    "tool-agent": AgentDefinition(
        description="Answers the task with the listed tools.",
        prompt="Answer the task using the listed tools. Each turn, call exactly one tool with complete "
               "arguments, or give your final answer. Do not guess a fact a tool can give you. "
               "When you answer, list the calls you relied on.",
        tools=TOOL_NAMES,
    ),
    "call-checker": AgentDefinition(
        description="Allows or rejects one proposed tool call.",
        prompt="Check one proposed tool call. Reject it if the tool is not listed, an argument is "
               "missing or malformed, or it repeats an earlier call. Give a one-line reason.",
    ),
}


class Verdict(BaseModel):
    allowed: bool
    reason: str


async def result_of(prompt: str, options: ClaudeAgentOptions) -> ResultMessage:
    async for msg in query(prompt=prompt, options=options):
        if isinstance(msg, ResultMessage):
            return msg
    raise RuntimeError("no result")


async def run(task: str) -> dict:
    calls: list[str] = []
    limit_hit = False

    async def gate(name: str, args: dict[str, Any], ctx: ToolPermissionContext) -> PermissionResultAllow | PermissionResultDeny:
        nonlocal limit_hit
        if name not in TOOL_NAMES:
            return PermissionResultDeny(message=f"{name} is not on the tool list.")
        if len(calls) >= MAX_CALLS:  # the gate: at most 6 tool calls
            limit_hit = True
            return PermissionResultDeny(message="Round limit reached: give your best final answer now.")
        # the checker runs in its own session: tool rules and calls only
        check = await result_of(
            f"Use the call-checker agent on this call and return its verdict.\n\nTools:\n{TOOL_RULES}\n\n"
            f"Proposed: {name} {args}\n\nPrevious calls:\n" + "\n".join(calls),
            ClaudeAgentOptions(agents=AGENTS, allowed_tools=["Agent"],
                               output_format={"type": "json_schema", "schema": Verdict.model_json_schema()}),
        )
        verdict = Verdict.model_validate(check.structured_output)
        if not verdict.allowed:
            return PermissionResultDeny(message=f"Rejected: {verdict.reason}")
        calls.append(f"{name} {args}")
        return PermissionResultAllow()

    options = ClaudeAgentOptions(
        agents=AGENTS,
        mcp_servers={"tools": SERVER},
        allowed_tools=["Agent"],  # tool calls are not pre-approved, so each one reaches the gate
        can_use_tool=gate,
    )
    answer = await result_of(f"Use the tool-agent agent on this task and return its answer:\n\n{task}", options)
    return {"answer": answer.result, "calls": calls, "incomplete": limit_hit}

Replace the two stubs with your real read-only tools, cap what each returns, and keep write tools out of this loop unless they get their own gate.

OpenAI Agents SDK, python, package openai-agents
from dataclasses import dataclass, field

from agents import (
    Agent, Runner, ToolGuardrailFunctionOutput, ToolInputGuardrailData, function_tool, tool_input_guardrail,
)
from pydantic import BaseModel

MAX_CALLS = 6
TOOL_RULES = "search_docs(query: str): search the docs\nget_order(order_id: str): fetch one order"


class Verdict(BaseModel):
    allowed: bool
    reason: str


@dataclass
class CallLog:
    calls: list[str] = field(default_factory=list)
    limit_hit: bool = False


checker = Agent(
    name="Call checker",
    instructions="Check one proposed tool call. Reject it if the tool is not listed, an argument is "
                 "missing or malformed, or it repeats an earlier call. Give a one-line reason.",
    output_type=Verdict,
)


@tool_input_guardrail
async def check_call(data: ToolInputGuardrailData) -> ToolGuardrailFunctionOutput:
    log: CallLog = data.context.context
    if len(log.calls) >= MAX_CALLS:  # the gate: at most 6 tool calls
        log.limit_hit = True
        return ToolGuardrailFunctionOutput.reject_content("Round limit reached: give your best final answer now.")
    proposal = f"{data.context.tool_name} {data.context.tool_arguments}"
    # the checker sees the tool rules and the calls, not the agent's conversation
    prompt = f"Tools:\n{TOOL_RULES}\n\nProposed: {proposal}\n\nPrevious calls:\n" + "\n".join(log.calls)
    verdict = (await Runner.run(checker, prompt)).final_output_as(Verdict)
    if not verdict.allowed:
        return ToolGuardrailFunctionOutput.reject_content(f"Rejected: {verdict.reason}")
    log.calls.append(proposal)
    return ToolGuardrailFunctionOutput.allow()


@function_tool(tool_input_guardrails=[check_call])
def search_docs(query: str) -> str:
    """Search the product docs and return the top 3 matches. Example: query="refund policy"."""
    return "stub: 3 matches"  # plug in your search index; cap the output


@function_tool(tool_input_guardrails=[check_call])
def get_order(order_id: str) -> str:
    """Fetch one order by id. Example: order_id="A-1042"."""
    return "stub: order summary"  # plug in your database, read-only


tool_agent = Agent(
    name="Tool agent",
    instructions="Answer the task using the listed tools. Each turn, call exactly one tool with complete "
                 "arguments, or give your final answer. Do not guess a fact a tool can give you. "
                 "When you answer, list the calls you relied on.",
    tools=[search_docs, get_order],
)


async def run(task: str) -> dict:
    log = CallLog()
    result = await Runner.run(tool_agent, task, context=log, max_turns=MAX_CALLS + 6)
    return {"answer": result.final_output, "calls": log.calls, "incomplete": log.limit_hit}

Replace the two stubs with your real read-only tools, cap what each returns, and keep write tools out of this loop unless they get their own gate.

Vercel AI SDK, typescript, package ai
import { anthropic } from '@ai-sdk/anthropic';
import { isStepCount, Output, tool, ToolLoopAgent } from 'ai';
import { z } from 'zod';

const MAX_CALLS = 6;
const TOOL_RULES = 'searchDocs(query: string): search the docs\ngetOrder(orderId: string): fetch one order';
const model = anthropic('claude-sonnet-5-5');

// stubs: plug in your search index and your database (read-only)
const searchDocs = async ({ query }: { query: string }) => `stub: 3 matches for ${query}`;
const getOrder = async ({ orderId }: { orderId: string }) => `stub: summary of ${orderId}`;

const checker = new ToolLoopAgent({
  model,
  instructions:
    'Check one proposed tool call. Reject it if the tool is not listed, an argument is missing ' +
    'or malformed, or it repeats an earlier call. Give a one-line reason.',
  output: Output.object({ schema: z.object({ allowed: z.boolean(), reason: z.string() }) }),
});

export async function run(task: string) {
  const calls: string[] = [];
  let limitHit = false;

  // the gate: every call passes the checker, and at most 6 calls run
  async function gated<T>(name: string, input: T, exec: (input: T) => Promise<string>) {
    if (calls.length >= MAX_CALLS) {
      limitHit = true;
      return 'Not run: round limit reached. Give your best final answer now.';
    }
    const proposal = `${name} ${JSON.stringify(input)}`;
    const { output } = await checker.generate({
      prompt: `Tools:\n${TOOL_RULES}\n\nProposed: ${proposal}\n\nPrevious calls:\n${calls.join('\n')}`,
    });
    if (!output.allowed) return `Rejected: ${output.reason}`;
    const result = await exec(input);
    calls.push(`${proposal} -> ${result.slice(0, 120)}`);
    return result;
  }

  const agent = new ToolLoopAgent({
    model,
    instructions:
      'Answer the task using the listed tools. Each turn, call exactly one tool with complete ' +
      'arguments, or give your final answer. Do not guess a fact a tool can give you. ' +
      'When you answer, list the calls you relied on.',
    tools: {
      searchDocs: tool({
        description: 'Search the product docs, top 3 matches. Example: { query: "refund policy" }',
        inputSchema: z.object({ query: z.string() }),
        execute: (input) => gated('searchDocs', input, searchDocs),
      }),
      getOrder: tool({
        description: 'Fetch one order by id. Example: { orderId: "A-1042" }',
        inputSchema: z.object({ orderId: z.string() }),
        execute: (input) => gated('getOrder', input, getOrder),
      }),
    },
    prepareStep: async () => (limitHit ? { toolChoice: 'none' as const } : {}), // at the limit, answer only
    stopWhen: isStepCount(MAX_CALLS + 6),
  });

  const { text } = await agent.generate({ prompt: task });
  return { answer: text, calls, incomplete: limitHit };
}

Replace the two stubs with your real read-only tools, cap what each returns, and keep write tools out of this loop unless they get their own gate.

Snippets are generated when the site is built and type-checked against the SDK versions listed in the repository. Treat them as a starting skeleton.

What goes wrong

  • Vague tool descriptions lead to wrong tool choices. Write each one as if for a new employee, with an example call.
  • Tools that return errors as long stack traces confuse the agent. Return a short, plain error it can act on.
  • Giving write tools to this loop without a gate means one bad call changes real data. Keep it read-only or add a gate.

Chain it

Its result can feed

Source