Agentic Architectures

Catalogue / Tools & Action

ReAct

Think out loud, act, read what happened, think again

Shape
loop
Model calls
1 per step, plus 1 observer call per action (typically 6 to 20)
Latency
medium
Complexity
low

Also known as Reason + Act, Thought–Action–Observation

1

Why does a tool-using agent lose its way on longer tasks?

Without a written reason for each call, an agent repeats lookups, forgets what it already learned and drifts from the goal. ReAct makes it write a short thought before every action and a plain observation after it. That trace steers the next step.

You may need it if

  • The agent calls the same tool twice with the same arguments.
  • Tasks need five or more dependent lookups, each one shaped by the last result.
  • When a run goes wrong, nobody can tell why the agent made a given call.
2

When is the reasoning trace just overhead?

Use it when

  • Each step depends on what the previous result revealed, so the path cannot be planned upfront.
  • You need an auditable record of why each action was taken.
  • Tasks run from five to twenty steps: long enough to drift, short enough for one context.

Avoid it when

What it costs

Model calls
1 per step, plus 1 observer call per action (typically 6 to 20)
Latency
medium
Complexity
low
3

How do thought, action and observation take turns?

The reasoner writes a thought and one action. The tool runs it. An observer reads the raw result and writes a short, factual observation into the trace. The reasoner reads the whole trace before its next thought. A step limit ends the loop.

action, stepsleftnext stepfinish, or steplimit reachedTask: The goal or question, the tool list, and optionally a rough plan to follow.TaskReasoner: Writes one thought, then one action, or a finish action with the answer.ReasonerTrace: The running log of thought, action and observation for every step.TraceTools: Runs the chosen action and returns its raw result.ToolsObserver: Reads the raw result and states what it shows, in one or two factual sentences.ObserverAnswer: The final answer, with the full trace that led to it.Answer
  1. Step 1 of 5

    A thought before the first action

    Asked "Why did this customer churn?", the reasoner writes "I should first check their support tickets from the last quarter", then the matching tool call.

  2. Step 2 of 5

    The action runs

    The tool runs exactly the action written in the trace. Its raw output, possibly long and messy, goes to the observer rather than straight back to the reasoner.

  3. Step 3 of 5

    The result becomes an observation

    The observer writes what the result shows, such as "Three tickets about invoice errors, last one unresolved". It adds no interpretation and no next step.

  4. Step 4 of 5

    The trace steers the next thought

    The reasoner rereads the whole trace and writes its next thought, which builds on the last observation. Repeated or pointless actions become visible in the log.

  5. Step 5 of 5

    Finish

    When the trace supports an answer, the reasoner writes a finish action. At the step limit it must finish with what it has and say what is still unknown.

What each part does
Task
The goal or question, the tool list, and optionally a rough plan to follow.
Reasoner
Writes one thought, then one action, or a finish action with the answer.
Trace
The running log of thought, action and observation for every step.
Tools
Runs the chosen action and returns its raw result.
Observer
Reads the raw result and states what it shows, in one or two factual sentences.
Answer
The final answer, with the full trace that led to it.
  • Trace → Reasoner: steps so far
  • Reasoner → Trace: thought and action
  • Reasoner → Tools: action, steps left
  • Tools → Observer: raw result
  • Observer → Trace: observation
  • Observer → Reasoner: next step
  • Reasoner → Answer: finish, or step limit reached

Where it connects

Entry
task
TaskQuestionPlan

A goal or question that needs several dependent tool calls, with the tool list. A plan, if given, is treated as a guide the reasoner may depart from.

Exit
answer
AnswerOutcome

When: The reasoner writes a finish action, or the step limit is reached.

The final answer, the full trace of thoughts, actions and observations, and a flag saying whether the step limit cut it short.

Working memory for one run
trace
Outcome

Ordered steps, each with a thought, the exact action, and the observation of its result. Discarded when the run ends unless returned with the answer.

4

What do I ask my assistant to set up?

The agents to launch

Reasoner

Work toward the goal one step at a time. Each turn, write one short thought stating what you know and what you need next, then exactly one action from the tool list, or FINISH with your answer. Never repeat an action whose observation is already in the trace.

Sees: The goal, the tool list, any given plan and the full trace. Never raw tool output.

Observer

You receive the raw result of one action. State in at most two sentences what it shows, with exact figures, dates and names. If it is empty or an error, say so. Do not interpret, recommend or guess.

Sees: The action that was run and its raw result. Not the reasoner's thought or the goal.

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 "ReAct" 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]

# ReAct
Think out loud, act, read what happened, think again.
Input: the task above. It must provide: A goal or question that needs several dependent tool calls, with the tool list. A plan, if given, is treated as a guide the reasoner may depart from. If something essential is missing, ask for it before starting.

Agents to launch:
- Reasoner: Work toward the goal one step at a time. Each turn, write one short thought stating what you know and what you need next, then exactly one action from the tool list, or FINISH with your answer. Never repeat an action whose observation is already in the trace.
  Context for this agent: The goal, the tool list, any given plan and the full trace. Never raw tool output.
- Observer: You receive the raw result of one action. State in at most two sentences what it shows, with exact figures, dates and names. If it is empty or an error, say so. Do not interpret, recommend or guess.
  Context for this agent: The action that was run and its raw result. Not the reasoner's thought or the goal.

Procedure:
1. Write the goal, the tool list with one-line descriptions, and the step limit. If a plan came in, attach it as a guide.
2. Launch the reasoner with the goal and the empty trace. Record its thought and action in the trace.
3. Run the action. Launch the observer on the action and its raw result, and append the observation to the trace.
4. Send the updated trace back to the reasoner and repeat. If the reasoner proposes an action already in the trace, return it with a note to choose differently.
5. At 12 steps, tell the reasoner to finish now with what it knows.

Stop rule: Stop when the reasoner writes FINISH, or after 12 actions. At the limit the reasoner must finish and list what remains unknown.

Exit:
- `answer`, when: The reasoner writes a finish action, or the step limit is reached. Deliver: The final answer, the full trace of thoughts, actions and observations, and a flag saying whether the step limit cut it short.

# Final deliverable
The final answer, the numbered trace (thought, action, observation per step), and a line stating whether the step 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 HumanMessage, SystemMessage
from langgraph.graph import END, START, StateGraph
from pydantic import BaseModel

MAX_STEPS = 12


def search(query: str) -> str:
    return f"stub: results for {query}"  # plug in your search API


def lookup(entity: str) -> str:
    return f"stub: record for {entity}"  # plug in your database


TOOLS = {"search": search, "lookup": lookup}
REASONER = ("Work toward the goal one step at a time. Write one short thought (two sentences at most), "
            "then exactly one action from the tool list, or FINISH with your answer as input. "
            "Never repeat an action whose observation is already in the trace.")
OBSERVER = ("You receive the raw result of one action. State in at most two sentences what it shows, "
            "with exact figures, dates and names. If it is empty or an error, say so. Do not interpret.")


class Step(BaseModel):
    thought: str
    action: str  # a tool name, or FINISH
    input: str  # the tool input, or the final answer


class State(TypedDict):
    goal: str
    trace: Annotated[list[dict], operator.add]
    pending: Step | None
    raw: str
    answer: str
    limit_hit: bool


model = init_chat_model("anthropic:claude-sonnet-5-5")
reasoner_model = model.with_structured_output(Step)


def render(trace: list[dict]) -> str:
    return "\n".join(f"{i}. {s['thought']} | {s['action']} | {s['observation']}" for i, s in enumerate(trace, 1)) or "(empty)"


async def reasoner(state: State) -> dict:
    actions = [s for s in state["trace"] if s["action"] != "(repeat)"]
    limit = len(actions) >= MAX_STEPS
    prompt = f"Goal: {state['goal']}\nTools: {', '.join(TOOLS)}\nTrace:\n{render(state['trace'])}"
    if limit:  # the step limit: finish now and say what is still unknown
        prompt += "\n\nStep limit reached. FINISH now and list what remains unknown."
    step = Step.model_validate(await reasoner_model.ainvoke([SystemMessage(REASONER), HumanMessage(prompt)]))
    if step.action == "FINISH" or limit:
        return {"answer": step.input or step.thought, "limit_hit": limit}
    if any(s["action"] == f"{step.action}({step.input})" for s in actions):
        note = {"thought": step.thought, "action": "(repeat)", "observation": "Already in the trace. Choose differently."}
        return {"trace": [note], "pending": None}
    return {"pending": step}


async def tools(state: State) -> dict:
    step = state["pending"]
    assert step is not None
    tool = TOOLS.get(step.action)
    return {"raw": tool(step.input) if tool else f"error: unknown tool {step.action}"}


async def observer(state: State) -> dict:
    step = state["pending"]
    assert step is not None
    # the observer sees the action and its raw result, not the thought or the goal
    action = f"{step.action}({step.input})"
    reply = await model.ainvoke([SystemMessage(OBSERVER), HumanMessage(f"Action: {action}\nRaw result:\n{state['raw']}")])
    return {"trace": [{"thought": step.thought, "action": action, "observation": reply.text}], "raw": ""}


def after_reasoner(state: State) -> str:
    return END if state["answer"] else "tools" if state["pending"] else "reasoner"


builder = StateGraph(State)
builder.add_node("reasoner", reasoner)
builder.add_node("tools", tools)
builder.add_node("observer", observer)
builder.add_edge(START, "reasoner")
builder.add_conditional_edges("reasoner", after_reasoner, ["tools", "reasoner", END])
builder.add_edge("tools", "observer")
builder.add_edge("observer", "reasoner")
graph = builder.compile()


async def run(task: str) -> dict:
    state = await graph.ainvoke(
        {"goal": task, "trace": [], "pending": None, "raw": "", "answer": "", "limit_hit": False},
        {"recursion_limit": 60},
    )
    return {"answer": state["answer"], "trace": state["trace"], "step_limit_reached": state["limit_hit"]}

Replace the stub tools with real ones; the full trace goes to the reasoner on every step, so summarise old steps (keeping their facts) for long runs.

Claude Agent SDK, python, package claude-agent-sdk
from claude_agent_sdk import AgentDefinition, ClaudeAgentOptions, ResultMessage, query
from pydantic import BaseModel

MAX_STEPS = 12


def search(query: str) -> str:
    return f"stub: results for {query}"  # plug in your search API


def lookup(entity: str) -> str:
    return f"stub: record for {entity}"  # plug in your database


TOOLS = {"search": search, "lookup": lookup}

AGENTS = {
    "reasoner": AgentDefinition(
        description="Chooses the next thought and action from the trace.",
        prompt="Work toward the goal one step at a time. Write one short thought (two sentences at most), "
               "then exactly one action from the tool list, or FINISH with your answer as input. "
               "Never repeat an action whose observation is already in the trace.",
    ),
    "observer": AgentDefinition(
        description="States what one raw tool result shows.",
        prompt="You receive the raw result of one action. State in at most two sentences what it shows, "
               "with exact figures, dates and names. If it is empty or an error, say so. Do not interpret.",
    ),
}


class Step(BaseModel):
    thought: str
    action: str  # a tool name, or FINISH
    input: str  # the tool input, or the final answer


async def delegate(agent: str, message: str, schema: type[BaseModel] | None = None) -> ResultMessage:
    # one fresh session per call, so each sub-agent sees only the message it is given
    options = ClaudeAgentOptions(
        agents=AGENTS,
        allowed_tools=["Agent"],
        output_format={"type": "json_schema", "schema": schema.model_json_schema()} if schema else None,
    )
    prompt = f"Delegate this to the {agent} agent, passing it verbatim, and return its reply unchanged:\n\n{message}"
    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:
    trace: list[dict] = []  # the trace store: thought, action, observation per step
    for n in range(MAX_STEPS + 1):
        lines = "\n".join(f"{i}. {s['thought']} | {s['action']} | {s['observation']}" for i, s in enumerate(trace, 1))
        prompt = f"Goal: {task}\nTools: {', '.join(TOOLS)}\nTrace:\n{lines or '(empty)'}"
        if n == MAX_STEPS:  # the step limit: finish now and say what is still unknown
            prompt += "\n\nStep limit reached. FINISH now and list what remains unknown."
        step = Step.model_validate((await delegate("reasoner", prompt, Step)).structured_output)
        if step.action == "FINISH" or n == MAX_STEPS:
            return {"answer": step.input, "trace": trace, "step_limit_reached": n == MAX_STEPS}
        action = f"{step.action}({step.input})"
        if any(s["action"] == action for s in trace):
            trace.append({"thought": step.thought, "action": "(repeat)", "observation": "Already in the trace. Choose differently."})
            continue
        tool = TOOLS.get(step.action)
        raw = tool(step.input) if tool else f"error: unknown tool {step.action}"
        # the observer sees the action and raw result, never the thought or the goal
        seen = await delegate("observer", f"Action: {action}\nRaw result:\n{raw}")
        trace.append({"thought": step.thought, "action": action, "observation": seen.result or ""})
    raise AssertionError("unreachable")

Replace the stub tools with real ones; the full trace goes to the reasoner on every step, so summarise old steps (keeping their facts) for long runs.

OpenAI Agents SDK, python, package openai-agents
from agents import Agent, Runner
from pydantic import BaseModel

MAX_STEPS = 12


def search(query: str) -> str:
    return f"stub: results for {query}"  # plug in your search API


def lookup(entity: str) -> str:
    return f"stub: record for {entity}"  # plug in your database


TOOLS = {"search": search, "lookup": lookup}


class Step(BaseModel):
    thought: str
    action: str  # a tool name, or FINISH
    input: str  # the tool input, or the final answer


reasoner = Agent(
    name="Reasoner",
    instructions="Work toward the goal one step at a time. Write one short thought (two sentences at most), "
                 "then exactly one action from the tool list, or FINISH with your answer as input. "
                 "Never repeat an action whose observation is already in the trace.",
    output_type=Step,
)
observer = Agent(
    name="Observer",
    instructions="You receive the raw result of one action. State in at most two sentences what it shows, "
                 "with exact figures, dates and names. If it is empty or an error, say so. Do not interpret.",
)


async def run(task: str) -> dict:
    trace: list[dict] = []  # the trace store: thought, action, observation per step
    for n in range(MAX_STEPS + 1):
        lines = "\n".join(f"{i}. {s['thought']} | {s['action']} | {s['observation']}" for i, s in enumerate(trace, 1))
        prompt = f"Goal: {task}\nTools: {', '.join(TOOLS)}\nTrace:\n{lines or '(empty)'}"
        if n == MAX_STEPS:  # the step limit: finish now and say what is still unknown
            prompt += "\n\nStep limit reached. FINISH now and list what remains unknown."
        step = (await Runner.run(reasoner, prompt)).final_output_as(Step)
        if step.action == "FINISH" or n == MAX_STEPS:
            return {"answer": step.input, "trace": trace, "step_limit_reached": n == MAX_STEPS}
        action = f"{step.action}({step.input})"
        if any(s["action"] == action for s in trace):
            trace.append({"thought": step.thought, "action": "(repeat)", "observation": "Already in the trace. Choose differently."})
            continue
        tool = TOOLS.get(step.action)
        raw = tool(step.input) if tool else f"error: unknown tool {step.action}"
        # the observer sees the action and raw result, never the thought or the goal
        seen = await Runner.run(observer, f"Action: {action}\nRaw result:\n{raw}")
        trace.append({"thought": step.thought, "action": action, "observation": seen.final_output_as(str)})
    raise AssertionError("unreachable")

Replace the stub tools with real ones; the full trace goes to the reasoner on every step, so summarise old steps (keeping their facts) for long runs.

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

const MAX_STEPS = 12;
const model = anthropic('claude-sonnet-5-5');

// stubs: plug in your search API and your database
const TOOLS: Record<string, (input: string) => Promise<string>> = {
  search: async (query) => `stub: results for ${query}`,
  lookup: async (entity) => `stub: record for ${entity}`,
};

const reasoner = new ToolLoopAgent({
  model,
  instructions:
    'Work toward the goal one step at a time. Write one short thought (two sentences at most), ' +
    'then exactly one action from the tool list, or FINISH with your answer as input. ' +
    'Never repeat an action whose observation is already in the trace.',
  output: Output.object({
    schema: z.object({
      thought: z.string(),
      action: z.string().describe('a tool name, or FINISH'),
      input: z.string().describe('the tool input, or the final answer'),
    }),
  }),
});

const observer = new ToolLoopAgent({
  model,
  instructions:
    'You receive the raw result of one action. State in at most two sentences what it shows, ' +
    'with exact figures, dates and names. If it is empty or an error, say so. Do not interpret.',
});

type TraceStep = { thought: string; action: string; observation: string };

export async function run(task: string) {
  const trace: TraceStep[] = []; // the trace store: thought, action, observation per step
  for (let n = 0; n <= MAX_STEPS; n++) {
    const lines = trace.map((s, i) => `${i + 1}. ${s.thought} | ${s.action} | ${s.observation}`).join('\n');
    let prompt = `Goal: ${task}\nTools: ${Object.keys(TOOLS).join(', ')}\nTrace:\n${lines || '(empty)'}`;
    if (n === MAX_STEPS) prompt += '\n\nStep limit reached. FINISH now and list what remains unknown.';
    const { output: step } = await reasoner.generate({ prompt });
    if (step.action === 'FINISH' || n === MAX_STEPS) {
      return { answer: step.input, trace, stepLimitReached: n === MAX_STEPS };
    }
    const action = `${step.action}(${step.input})`;
    if (trace.some((s) => s.action === action)) {
      trace.push({ thought: step.thought, action: '(repeat)', observation: 'Already in the trace. Choose differently.' });
      continue;
    }
    const tool = TOOLS[step.action];
    const raw = tool ? await tool(step.input) : `error: unknown tool ${step.action}`;
    // the observer sees the action and raw result, never the thought or the goal
    const { text } = await observer.generate({ prompt: `Action: ${action}\nRaw result:\n${raw}` });
    trace.push({ thought: step.thought, action, observation: text });
  }
  throw new Error('unreachable');
}

Replace the stub tools with real ones; the full trace goes to the reasoner on every step, so summarise old steps (keeping their facts) for long runs.

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

  • Thoughts that grow into essays cost tokens without adding direction. Cap each thought at two sentences.
  • An observer that adds advice turns into a second reasoner. Keep it to what the result shows.
  • A trace that outgrows the context gets truncated silently. For long runs, summarise old steps but keep every observation's facts.

Chain it

Its result can feed

It can take the result of

On a condition

Source