All chapters
  1. Start hereOne agent asks. Another answers. The rest is the contract between them
  2. Foundations · 1One model, one tool, two agents: who is who, and who is responsible
  3. Foundations · 2Message passing: sender, recipient, payload, address and correlation
  4. Foundations · 3Topologies: central orchestrator, peer-to-peer and hierarchy
  5. Mechanics · 4Request and reply, or a task: synchronous versus asynchronous exchange
  6. Mechanics · 5Contracts: messages, artifacts, typed schemas, errors and versions
  7. Mechanics · 6The task lifecycle: submitted, working, input-required, completed, failed, canceled
  8. Mechanics · 7Discovery: Agent Cards, skills and how an agent says what it can do
  9. Protocol · 8A2A: the Agent2Agent protocol, part by part
  10. Protocol · 9A2A versus MCP: delegating to an agent versus calling a tool
  11. Protocol · 10Handoff, delegation or shared state: three ways to work together
  12. Production · 11How updates arrive: streaming, push notifications, callbacks, polling and queues
  13. Production · 12Security: identity, delegated scopes, trust across domains, authorization
  14. Production · 13Reliability: retries, idempotency, order, timeouts and compensation
  15. Production · 14Observability: one trace across three agents
  16. Reference · 15Frameworks: A2A SDKs, LangGraph, AutoGen, CrewAI and plain code
  17. Reference · 16Advanced: consensus claims, coordination failure, cost and isolation
  18. ReferenceGlossary
  19. AboutAbout this site and its sources
Foundations · 1

One model, one tool, two agents: who is who, and who is responsible

A model, a tool and an agent are three different things. What changes when the thing you call is another agent, and how to draw the line between two agents' responsibilities.

What you will understand
Three things, three words
A model predicts text. A tool answers. An agent decides what to do next.
When the callee is an agent
It may take long, ask back, refuse, or do the work a way you cannot see.
Where to cut
How to draw the line between two agents, and when not to split at all.

In the first version of the insurer's software there was one agent. When it needed the roof age, it called a function, get_roof_assessment("SUB-1004"), and 180 milliseconds later it had an answer: 22 years. That function never asked a question, never took an hour, and never said no.

After the split, the intake agent no longer calls that function. It asks the assessment agent to "collect the evidence for SUB-1004". In case UW-402 the assessment agent answers, 200 milliseconds later, with something the old function could never return: a question. The roof age is missing on the application and the roof-data provider has no record. Before it can go on, it needs the broker to say how old the roof is. The broker answers fifteen minutes later.

The intake team had written the call as if it were the old function: send, wait, get a result. That code has no place to put a question, and no reason to wait fifteen minutes. The bug is not in the message format. It is in a wrong idea of what is on the other side. This page makes that idea exact.

Model, tool, agent#

Three words are often used as if they were one. They name three different things, and the difference decides how you talk to each.

A model is the language model itself: you give it text (and sometimes images), it gives back predicted text. For example, you send "Which facts does this email contain?" with the broker's email, and it answers with a list. A model has no memory between calls and runs no code by itself.

A tool is a function that the agent's program runs when the model asks for it. It takes arguments and returns a result. For example, get_roof_assessment(submission_id) returns a roof age, a source and an evidence id. A tool answers. It does not decide what to do, it does not ask questions, and the same input gives the same kind of answer.

An agent is a program that calls a model in a loop and runs the tools the model asks for, until the work is done. For example, the assessment agent receives "collect the evidence for SUB-1004", decides which tools to call and in which order, notices that the roof age is missing, and asks for it. An agent decides.

Diagram: Model, tool, agent · three different things

A model predicts text and runs nothing. A tool is a function that answers. An agent is the loop around them: it asks the model what to do, runs the tools, and decides when the work is done or when it must ask someone.

  1. Model
    1. Text in, text out: A language model call. No memory between calls, runs no code.
  2. Tool
    1. Arguments in, result out: A function the agent's program runs when the model asks for it.
  3. Agent
    1. Request in, result or question out: A program that calls the model in a loop and runs tools until done. It can ask back, take long or refuse.

The word that covers all the participants of a system, whether agent, tool or person, is actor: anything that can send or receive in the example. The underwriter is an actor. The roof-data provider is an actor reached by a tool call. The three agents are actors that exchange messages.

Plain English. A tool is a vending machine: press the button, get the item. An agent is a colleague: you ask, they think about it, they may come back with a question, and they may tell you they will not do it.
ModelToolAgent
What you give itTextArguments that match a schemaA request: a goal and the facts it needs
What you get backPredicted textA resultA result, a question, a refusal, or "still working"
How longSecondsMilliseconds to secondsSeconds to hours
Who chooses the stepsNobody: one predictionThe code, fixedThe agent, at run time
How you reach itA model callA tool callA message

The last row is the one this site builds on. A tool is called. An agent is asked.

What changes when the callee is an agent#

When the thing on the other side of a call is an agent, five properties change. Each one becomes a chapter later on this site, so it is worth naming them now.

It decides. The callee chooses its own steps. In UW-403 the assessment agent calls three tools; in UW-406 it calls the roof tool twice because the first call timed out. The caller does not choose and often does not see these steps. What the caller can rely on is the contract of the result, not the path. Contracts is about that contract.

It can ask back. A tool fails or succeeds. An agent can stop halfway and ask for something it needs, as in UW-402. The caller must have a way to receive a question and send an answer that resumes the same work. That is the input-required state of Task lifecycle.

It can take long. A tool call that takes fifteen minutes is broken. An agent task that takes fifteen minutes because it waits for a broker is normal. The caller cannot hold a connection open that long, so it needs an id now and the result later. Sync and async covers that.

It can refuse. A request can be malformed, unauthorized, or outside what the agent does. A refusal must be an answer with a name, not silence. In the example a refused request becomes a task in state rejected, with a typed error.

It is opaque. The caller sees what the agent says, not what it holds. The intake agent never sees the roof-data provider, the guidance index or the past decisions; only the assessment agent can reach them. An opaque agent is one whose tools, memory and reasoning are hidden behind its messages. That is a feature (the assessment team can change its sources without telling anyone) and a risk (the caller must trust a description it cannot inspect, which Discovery takes up).

Before AI. A Spring service that calls another service over REST knows that the other side may be slow, may fail, and may have changed. That experience transfers. What is new is that the other side may legitimately answer with a question, and that its path through its own dependencies may differ from one request to the next. A REST contract describes endpoints; an agent's contract must also describe what it may ask you.

The smallest primitive: who owns which responsibility#

Splitting one agent into several is drawing lines through a list of responsibilities. A responsibility boundary is the line between what one agent owns and what another owns: which goal, which tools, which data, which decisions. A good boundary means each agent can be changed, tested and secured without the others.

The example draws three boundaries:

Diagram: Three agents, one person, five tools · who owns what

Read left to right along the work. Each agent owns one goal and reaches its tools by tool call; agents reach each other only by message. The person at the end owns the decision, and no agent holds the scope to make it.

  1. Intake agent
    1. Broker's email: The quote request as the broker wrote it. Read once.
    2. Submission: The facts of the email as one JSON record. Every later step reads this, never the email.
  2. Assessment agent
    1. get_roof_assessment: Roof-data provider (stand-in). Answers with a roof age and an evidence id.
    2. search_guidance: Searches the underwriting guidance. Its passages are marked untrusted.
    3. find_similar_decisions: Past decisions on similar buildings, each with its policy version.
    4. Evidence artifact: One structured result: every fact with an id and a source, plus the gaps.
  3. Underwriting agent
    1. check_eligibility: Deterministic rules of the policy fixture. Same input, same answer.
    2. record_recommendation: Stores the recommendation for the underwriter. Needs recommendation:write and an idempotency key.
  4. Underwriter
    1. Decision: The person decides in the underwriter cockpit. Only this role holds decision:write.
ActorKindOwnsHolds the scopeReaches
intake agentagentthe email, the submission, the conversation with the brokerevidence:readthe assessment agent (or a coordinator) by message
assessment agentagentcollecting evidence, naming the gapsevidence:readthe three read tools, by tool call
underwriting agentagentthe rules, the recommendation, the escalationevidence:read, recommendation:writecheck_eligibility and record_recommendation, by tool call
underwriterpersonthe decisiondecision:writethe underwriter cockpit
roof-data provider, guidance index, past decisions, rulestoolsnothing: they answernonenothing

Three things in the table matter more than the names. First, each agent holds only the scopes its job needs; the assessment agent can never write a recommendation, and no agent can write a decision. Second, tools sit inside one agent's boundary; they are never shared by sending messages to them. Third, the person is an actor with the one responsibility no agent has.

The insurance example#

Case UW-402 shows every property at once. The application has no roof age, and the roof-data provider has no record. Here is the run in the orchestrator topology (the coordinator in the middle routes the messages). The agents here are scripted stand-ins, so these results show how the mechanism works, not how good any model is.

cd examples/uw-agents
/opt/homebrew/bin/python3 run_case.py --case UW-402 --dry-run
UW-402 · topology orchestrator · run run-5e02 · agents: scripted stand-ins (no model called)
  time ms  from                 to                 type          state           ids
       50  intake-agent       → coordinator        task.request  -               msg-0001 corr msg-0001 task -        try 1
       70  coordinator        → intake-agent       task.status   working         msg-0002 corr msg-0001 task task-c1  try 1
       70  coordinator        → assessment-agent   task.request  -               msg-0003 corr msg-0003 task -        try 1
       90  assessment-agent   → coordinator        task.status   working         msg-0004 corr msg-0003 task task-a1  try 1
      270  assessment-agent   → coordinator        task.status   input-required  msg-0005 corr msg-0003 task task-a1  try 1
      290  coordinator        → intake-agent       task.status   input-required  msg-0006 corr msg-0001 task task-c1  try 1
   900310  intake-agent       → coordinator        task.input    -               msg-0007 corr msg-0007 task task-c1  try 1
   900330  coordinator        → intake-agent       task.status   working         msg-0008 corr msg-0001 task task-c1  try 1
   900330  coordinator        → assessment-agent   task.input    -               msg-0009 corr msg-0009 task task-a1  try 1
   900350  assessment-agent   → coordinator        task.status   working         msg-0010 corr msg-0003 task task-a1  try 1
   900740  assessment-agent   → coordinator        task.artifact completed       msg-0011 corr msg-0003 task task-a1  try 1
   900760  coordinator        → underwriting-agent task.request  -               msg-0012 corr msg-0012 task -        try 1
   900780  underwriting-agent → coordinator        task.status   working         msg-0013 corr msg-0012 task task-u1  try 1
   900826  underwriting-agent → coordinator        task.artifact completed       msg-0014 corr msg-0012 task task-u1  try 1
   900846  coordinator        → intake-agent       task.artifact completed       msg-0015 corr msg-0001 task task-c1  try 1
messages: 15 sent · 15 delivered · 0 duplicates dropped · 0 stale updates ignored · 0 deadlines fired
tasks (caller's view): workflow completed · evidence completed · recommendation completed
recommendation: approve · citations - · missing - · evidence complete · routed to the underwriter · stated_confidence 0.9
tool calls: get_roof_assessment 1 · search_guidance 1 · find_similar_decisions 1 · check_eligibility 1 · record_recommendation 1
rows stored: 1 · human_decision: none (no person has decided yet)
trace: 1 trace_id · 42 spans · last message at 900866 ms · run ends at 900866 ms (simulated)
expected vs actual: PASS (10 of 10 checks)

At 270 ms the assessment agent says input-required on its task task-a1. The question travels up to the intake agent, which asks the broker. At 900,310 ms (fifteen simulated minutes later) the answer, 12 years, comes back as a task.input that names the same task. The same task resumes and completes. The recommendation is approve. No connection was held open for fifteen minutes and nothing was started twice.

An executable demonstration: an agent can refuse#

The fourth property, refusal, is in the code every agent shares. This is Agent._on_request in examples/uw-agents/agents.py, verbatim. It shows what an agent does with a request before any work: check the shape, check the credentials, then accept or reject.

def _on_request(self, msg: dict[str, Any], bus: Any, span: dict[str, Any]) -> None:
    """Validate, authorize, accept. A refused request still becomes a task, in state `rejected`."""
    task = Task(task_id=f"task-{self.prefix}{len(self.tasks) + 1}", run_id=msg["run_id"], kind=KIND_OF.get(msg["schema"], "?"),
                owner=self.address, caller=msg["from"], request=msg)
    self.tasks[task.task_id] = task
    task.span = self.tracer.start(self.address, "task", f"{task.kind} task", span, task_id=task.task_id,
                                  attempt_number=msg["attempt_number"], message_id=msg["message_id"],
                                  correlation_id=msg["correlation_id"])
    problems = validate(msg["schema"], msg["payload"], accepts=self.accepts)
    verdict = authorize(msg["auth"], msg["schema"], audience=self.address)
    if problems:
        self.update(task, bus, "reject", error=error(problems[0]["code"], problems[0]["message"]))
    elif not verdict["allow"]:
        self.update(task, bus, "reject", error=error("UNAUTHORIZED", verdict["reason"]))
    else:
        self.update(task, bus, "start")
        self.start_work(task, bus)

Two design choices are visible. A refused request still gets a task id, so the caller hears a named refusal (rejected, with an error code) instead of silence. And the check happens at the receiver, against the token in the message, not at the sender. Among the 45 tests of the example, test_receiver_rejects_bad_request sends a request with an empty payload and checks that the task ends rejected, and test_authorize_reasons checks the reasons of the scope check. /opt/homebrew/bin/python3 -m unittest in the example folder runs them all, and they pass.

A failure mode: treating an agent like a tool#

Here is what goes wrong when a caller is written as if the callee were a function. Suppose the intake side waited on the line for a result, with the 30-second timeout it would give a slow REST service. In UW-402 the answer would never come in time: the work needs a person, and the person needs fifteen minutes. The caller would time out, assume failure, and send the request again. The assessment agent would then hold two tasks for one submission, both waiting for the same answer from the broker, and the broker would be asked twice.

The same mistake in the other direction is quieter. If the intake agent assumed that the assessment agent's evidence came from one fixed source, it might cite "the provider" in its own messages. When the assessment team adds a second source, the intake agent's text is now wrong, and nothing breaks loudly. An opaque agent's internals are not part of its contract. Only its messages are.

Production pitfall. "We wrapped the other agent as a tool so our agent can call it" is common, and sometimes fine. It hides exactly the five properties above: the wrapper must still handle a question back, a long wait and a refusal, or it turns them into a timeout. A2A vs MCP shows what such a wrapper loses.

How frameworks draw these lines#

Libraries name the same three things differently. Most give you an object for an agent (a model, instructions and a set of tools), a way to declare a tool as a typed function, and some way for one agent to pass work to another. The A2A protocol, a standard for messages between agents, does not care what is inside an agent at all: it describes only what crosses the boundary, which is the point of an opaque agent. How each named library draws the line is on Frameworks, read from each library's own documentation.

What this is not. This page separates the actors; it does not teach how to design a good tool. Tool schemas, tool execution and tools served over MCP belong to tools.sammuthu.com. What the model inside one agent can see at a given moment belongs to context.sammuthu.com.

Checklist: before you split an agent#

The same idea for a coding agent. A planning agent that calls run_tests() as a tool gets pass or fail. A planning agent that asks a test agent to "find out why the suite is red" gets something richer and slower: the test agent may run the suite twice, bisect, and come back asking which branch to compare against. The first is a tool call; the second is a request to an agent, and the planning agent must be written for questions and long waits. The runtime inside each of those agents is the subject of harness.sammuthu.com.

When not to splitEvery boundary is a distributed system you now own

A split is justified by something that one agent cannot give: separate ownership, separate credentials, separate release cycles, separate failure domains, or a callee that must be replaceable by another vendor's agent. It is not justified by prompt length or by the wish to give each step a persona. Those are context and instruction problems inside one agent, and a split turns them into messages that can be lost, duplicated and delayed.

A useful test is the shape of the traffic. If two agents exchange many small messages per unit of work, keep shared state, or must agree on every intermediate step, the line is in the wrong place: they are one component pretending to be two. If they exchange one request and one artifact per unit of work, with a contract that rarely changes, the line is in a good place. In the example the assessment agent and the underwriting agent exchange exactly one artifact per run.

Opacity as a design propertyWhat the caller may assume, and what it must not

Opacity is what lets two teams evolve independently, and it moves risk to the contract. The caller may assume what the contract says: the artifact's schema and version, the named errors, the states the task may pass through, the scopes it needs. It must not assume the callee's tools, its model, its retry policy or its timing. Every assumption of the second kind is a hidden coupling that fails silently on the callee's next release.

Two consequences follow for a design review. Evidence must be carried, not implied: the artifact in the example names every piece of evidence with an id and a source, so the underwriting agent can cite it without knowing how it was found. And observability must cross the boundary without breaking opacity: trace context travels in the message, so a span tree shows that the assessment agent called a tool, without the caller depending on which one. Tracing shows this on a case.

The person as an actorWhy the decision is not just another message

The underwriter appears in the actor table on purpose. The decision is the one act in the system that no agent may perform, and the example enforces it in two places: only the underwriter role holds decision:write, and the audit event of a decision names a role, not an agent. Modeling the person as an actor with a scope, rather than as a comment in the code, makes "the model recommends; a person decides" a property you can test.

A person is also the slowest actor. In UW-408 the underwriter's decision arrives 90 simulated minutes after the recommendation. Any design that holds a connection, a lock or a model context open while a person thinks will fail on the first real afternoon.

In one breath#

A model predicts text, a tool answers, an agent decides. When the thing you call is another agent, it may take long, ask back, refuse, or do the work a way you cannot see, so you send it a message rather than call it. Splitting one agent into several means drawing responsibility boundaries: each agent owns one goal, its own tools and only the scopes it needs, and the decision stays with a person.

Next: if agents are asked, not called, the question is what exactly travels between them. Messages takes one message apart: sender, recipient, payload, address, and the id that lets a reply find its request.