SOLID for AI Agents: The Charter Is the Interface, and KISS Decides When to Split

TL;DR

• For an agent, a responsibility is a tool group, and the unit of design is the charter: the one line a router reads to decide who gets the work. Split by tools and the router has a question it can answer. Split by verbs and it guesses.
• A charter is a contract, and a small model fills every gap you leave in it. My file specialist had no calculator, added six numbers in its head and reported a wrong total with full confidence. One sentence of refusal in its charter fixed it. The router then did the same sum itself, and needed its own sentence.
• Open/closed and dependency inversion paid in full. The supervisor arrived as a sibling module with the original graph byte-identical, and a backend swap to a model released five days earlier was one branch in a factory function.
• Liskov is where agent systems break. Two chat models behind the same interface did not accept the same message list, and a 3B specialist that got 9 of 10 tasks right looped on the tenth until the recursion limit stopped it. Termination was a postcondition I had never written down, so I put it in code.
• KISS won most of the argument. On six tasks the split matched the single agent’s accuracy, 16 of 18 each, and needed more model calls on every one of them. Split when a measurement says the split pays, and keep one agent with fewer tools until then.
• Built in the same LangGraph lab I started measuring with evals. The charter argument is the tool description problem one level up, with agents as the callers.

Why one agent with every tool isn’t enough

The default agent is one model with every tool bound to it. Mine had eight: a calculator, web search, four file operations on a sandboxed workspace, two memory operations. One system prompt describes all of them and one loop runs them.

Right starting point, and the people who build these for a living say so too. Anthropic’s Building effective agents tells you to find “the simplest solution possible, and only increasing complexity when needed”. OpenAI’s practical guide to building agents says to “maximize a single agent’s capabilities first”. Across every task I measured, the single agent answered correctly as often as anything I replaced it with.

It is also a god object, and it fails the way god objects fail.

1. One prompt is the policy for eight jobs. The prompt says to use a tool “whenever it would make your answer more accurate than guessing”. That one sentence decides when to search, when to compute, when to read and when to remember. On the task that needs three tools in one turn (read a report, total it, remember a fact), one run read the file, stored the fact, skipped the calculator and answered 706,350. The right total is 624,400.

2. Every tool is in reach on every turn. On the plain “total this report” task, one run had the calculator bound, read the file, and added the six numbers in its head anyway: 1,002,200. A greeting carries the same eight tool schemas as a three-tool task. Nothing in the design says which tools belong to which kind of request, so the model decides that too, on every call.

3. It never lets go of what it read. read_file on a 5,316-character report puts the whole report in the message list, and it stays there. Two turns later, a one-word greeting still has the report in its context.

Decomposition is the textbook answer to all three. So I decomposed by the textbook, one principle at a time, and kept the single agent next to it to check whether the textbook was right.

Single responsibility: one specialist per tool group

Robert C. Martin’s own restatement of the single responsibility principle is “Gather together the things that change for the same reasons.” For an agent, the things that change together are a set of tools, the rules for using them and the prompt that carries those rules. So I split the eight tools into four specialists. Each one is a name, a charter (the one-line description the supervisor reads when deciding who to call), a system prompt of its own, and a tuple of tools:

1
@dataclass(frozen=True)
2
class Specialist:
3
    name: str
4
    charter: str          # what the supervisor reads when choosing
5
    prompt: str           # the specialist's own system prompt
6
    tools: tuple
7

8
    @property
9
    def handoff(self) -> str:
10
        return f"ask_{self.name}"
11

12

13
SPECIALISTS = (
14
    Specialist(
15
        name="analyst",
16
        charter="Arithmetic. Any sum, product, percentage or total, however simple.",
17
        # "Never compute in your head" was the first version and a 7B model ignored it
18
        # every time, answering 17*23 = 411 from memory. What it obeys is an instruction
19
        # about the *first action*, not about the reasoning.
20
        prompt=(
21
            "You are the analyst. Your first action for any arithmetic instruction is a "
22
            "calculator call, including for a sum you are sure you already know. You may "
23
            "not answer before the calculator has replied."
24
        ),
25
        tools=(calculator,),
26
    ),
27
    Specialist(
28
        name="librarian",
29
        charter=(
30
            "The user's files: listing them, reading them, writing and deleting them. "
31
            "Returns what a file says. Does no arithmetic on it."
32
        ),
33
        prompt=(
34
            "You are the librarian. You work inside the user's sandboxed workspace. You "
35
            "have no calculator and you never summarize.\n"
36
            "If the instruction is about numbers in a file, reply with every one of those "
37
            "numbers verbatim, as a single line of `label=value` pairs, and nothing else."
38
        ),
39
        tools=(list_workspace, read_file, write_file, delete_file),
40
    ),
41
    # ... archivist (memory), researcher (web) ...
42
)

Split by tool ownership, not by verb. The tempting split is “a planner, a researcher, a writer”. It sounds like a team and routes like a coin flip, because nothing in a request tells you whether it is planning or writing. Splitting by tools gives the router a question it can answer: does this step need the filesystem, arithmetic, the web, or memory. Each specialist now has one reason to change. A new file operation touches the librarian and nothing else.

Write the refusal into the charter. The librarian’s charter ends with “Does no arithmetic on it”, and its own prompt repeats the rule in the second person so it holds even when the supervisor forgets. Before those two sentences existed, the librarian read the report and reported a total anyway. It has no calculator. It added six numbers in its head, got it wrong, and said so in the same tone it uses when it is right. An agent that cannot do the thing will fake the thing unless the contract tells it to refuse.

The router needs the same rule. Once the librarian returned honest raw numbers, the supervisor started adding them itself and skipped the analyst. Two of three runs on the single-report task did it, landing on 594,600 and 593,400. What I added was a line that names the tempting case: “You do no arithmetic yourself, ever, not even a sum of two numbers already in front of you.” Even with it, the failure comes back on some runs at temperature 0.7. A prohibition that does not name the temptation is a suggestion, and one that does is still a prompt, which is why the next sections move rules out of prompts and into code.

A responsibility also needs a caller. On an earlier run with qwen2.5:7b as the router, the supervisor never once handed work to the archivist on a task that asked it to remember something, 0 of 6. The archivist was correct and had nothing to do. A specialist the router does not pick for its own job does not exist, so test the routing to each charter, not only the specialist behind it.

Interface segregation: charter in, one line out

Interface segregation says no client should depend on methods it does not use. In an agent, the client is a model, and it depends on everything in its context. So the interface has two directions: what a caller can ask for, and what comes back.

The way in is the handoff. The supervisor holds four tools, ask_analyst, ask_librarian, ask_archivist and ask_researcher, and no tool that does real work. Their descriptions are the charters:

1
def _handoff_tools() -> list:
2
    """Schemas, not implementations.
3

4
    Binding these tells the model what routing decisions exist. Nothing calls the
5
    functions: `specialist_node` intercepts the call and runs the sub-agent. A
6
    handoff tool that executed itself would run outside the graph, which means
7
    outside the checkpointer and outside the trace tree.
8
    """
9
    tools = []
10
    for spec in SPECIALISTS:
11
        def _make(spec: Specialist):
12
            @tool(spec.handoff)
13
            def _handoff(task: str) -> str:
14
                """placeholder"""
15
                raise RuntimeError("handoff tools are routed by the graph, never invoked")
16

17
            _handoff.description = (
18
                f"Hand one instruction to the {spec.name}. {spec.charter} "
19
                f"The {spec.name} cannot see this conversation, so `task` must be "
20
                "self-contained."
21
            )
22
            return _handoff
23

24
        tools.append(_make(spec))
25
    return tools

A handoff is a schema the graph executes. The ask_* tools have no bodies. The graph intercepts the call and runs the sub-agent itself, so every specialist call lands in the checkpointer and in the trace tree. A handoff that executes itself runs outside both, and a multi-agent run you cannot resume or inspect is one you cannot debug.

The task has to stand on its own. The specialist starts blind: its own system prompt plus the one instruction the supervisor wrote. That forces the supervisor to put everything into task, including the six numbers the librarian just returned. Anthropic’s write-up of their multi-agent research system lists what a delegation needs: “an objective, an output format, guidance on the tools and sources to use, and clear task boundaries.” My charters carry the boundaries and the specialist prompts carry the output format. Without both, their subagents duplicated each other’s work, and mine faked each other’s.

Narrow what comes back too. The librarian answers in one line of label=value pairs and never pastes the file. Only that line returns to the supervisor, inside a ToolMessage. The report never enters the router’s context, so the router cannot be distracted by a 5,316-character document it has no tool to act on. I also built the opposite, a full-history handoff where the specialist inherits the whole conversation and its whole transcript comes back. That is langgraph-supervisor’s output_mode="full_history". On the three-tool task it got 1 of 3 right.

There is a counter-argument, and it is a good one. Walden Yan’s Don’t Build Multi-Agents argues for sharing full traces, because “actions carry implicit decisions, and conflicting decisions carry bad results”. That holds when the specialists make decisions that have to fit together, like two subagents drawing a background and a bird for the same game. Mine return facts: a list of numbers, a filename, a confirmation. Facts compose. Decisions do not, so a narrow return fits when a specialist reports and a shared trace fits when it designs.

Open/closed and dependency inversion: the boundaries that cost nothing

These two principles paid outright, and they paid for each other.

The supervisor was added. src/agent/graph.py, the single agent, is byte-identical to the version before the split. So are the state reducers, the persistence layer, the tools and the eval harness. The supervisor is a sibling module that reuses the same tools and the same model factory, so one runner can invoke both architectures through the same graph.invoke({"messages": [...]}) and grade them with the same graders. The branch added 6,099 lines across 18 files and deleted 8. Open for extension, closed for modification, and it is the only reason the comparison below compares the same program twice.

The graph depends on a BaseChatModel. Halfway through, I swapped the serving layer. Ollama out, llama-server from the MBZUAI-IFM fork of llama.cpp in, running K2 Horizon 7B five days after its release. Different wire format, different client library, different model family.

1
def get_model(
2
    model: str | None = None,
3
    *,
4
    provider: str | None = None,
5
    reasoning: bool | None = None,
6
) -> BaseChatModel:
7
    """Chat model factory for whichever local server serves this call.
8

9
    Every argument is an override with a settings-shaped default, which is what
10
    lets one graph run heterogeneously: the supervisor on llama-server and a
11
    specialist on Ollama, in the same turn, without either node knowing.
12
    """
13
    provider = provider or settings.provider
14

15
    if provider == "llamacpp":
16
        return init_chat_model(
17
            model or settings.llamacpp_model,
18
            model_provider="openai",          # llama-server speaks the OpenAI wire format
19
            base_url=settings.llamacpp_base_url,
20
            api_key="llama.cpp-does-not-check-this",
21
            temperature=0.7,
22
        )
23

24
    return init_chat_model(
25
        model or settings.ollama_model,
26
        model_provider="ollama",
27
        base_url=settings.ollama_base_url,
28
        temperature=0.7,
29
    )

The backend change added lines in config.py and in this file. The graph did not change. You find out dependency inversion was worth it on the day something you did not plan for shows up. Here it was a model that upstream llama.cpp cannot load (unknown model architecture: 'k2-horizon') becoming the thing I wanted to measure.

Each charter can name its own model. The same boundary goes one level down. Specialist gained an optional model field, and one helper returns the same four charters answered by a different model:

1
def with_backend(model: str, *, provider: str | None = None, reasoning: bool | None = None):
2
    """The same four specialists, answered by a different model.
3

4
    Names, charters and tool tuples are identical, so the supervisor's prompt and
5
    its handoff schemas are byte-for-byte what they were.
6
    """
7
    return tuple(replace(spec, model=model, provider=provider, reasoning=reasoning) for spec in SPECIALISTS)

The router keeps the hard job, reading a request and choosing who does it. A specialist that reads one instruction, calls one tool and reports a number has a much smaller job, and nothing in the graph has to know which model does it. That is the promise of the abstraction. The next section is what happened when I took it at its word.

Liskov: the substitute has to honour the whole contract

Liskov and Wing’s behavioural notion of subtyping says that anything you can prove about the supertype must also hold for the subtype. For agents, the supertype is “a chat model that serves this charter”, and every model you put behind it is a subtype. I broke that promise twice, and neither break was a wrong answer.

Two chat models, two different interfaces. My full-history handoff first echoed the specialist’s transcript back as a run of AIMessages. Ollama serving qwen accepted it. K2 Horizon’s chat template raises Cannot have 2 or more assistant messages at the end of the list. Both are a BaseChatModel, and they do not accept the same message lists. The fix was to fold the transcript into the ToolMessage that already goes back:

1
# src/agent/supervisor.py, inside specialist_node
2
if scope == "full":
3
    # It rides inside the ToolMessage rather than as a run of extra AIMessages,
4
    # because K2 Horizon's chat template refuses a list with two assistant
5
    # messages in a row. Same tokens, legal shape.
6
    echoed = "\n".join(f"[{spec.name}] {m.content}" for m in transcript)
7
    answer = f"{answer}\n\n{echoed}"
8
out.append(ToolMessage(content=answer, tool_call_id=call["id"], name=call["name"]))

The type says what a model accepts. The chat template decides it. Test against the strictest backend you plan to run, because that one defines the interface.

A substitute that answers right and never finishes. With qwen3.5:4b behind the four charters, the system got the same 10 of 10 as K2 behind them. With llama3.2:3b, one run of the single-report task made 49 model calls and stopped on LangGraph’s recursion limit. The librarian kept returning something the supervisor could not use, and the supervisor kept routing back to it. The other nine tasks were correct. The loop was the failure. “Terminates with something the caller can use” was a precondition of every charter I wrote, and it appears in none of them.

Put the postcondition in code. A charter is a prompt, and a prompt is a request. The guarantee lives in the loop that runs the specialist:

1
# A specialist that has not answered in this many model calls is looping, not
2
# working. The supervisor gets told that, and decides what to do about it.
3
MAX_SPECIALIST_STEPS = 6
4

5
def run_specialist(spec: Specialist, task: str, ...) -> tuple[str, list[AnyMessage]]:
6
    ...
7
    for _ in range(MAX_SPECIALIST_STEPS):
8
        response = model.invoke([SystemMessage(spec.prompt), *messages], ...)
9
        if not response.tool_calls:
10
            return response.content, transcript
11
        ...
12

13
    return (
14
        f"The {spec.name} did not finish within {MAX_SPECIALIST_STEPS} steps. "
15
        "Tell the user that part could not be completed.",
16
        transcript,
17
    )

The cap bounds one specialist. The 3B run escaped it anyway, because each visit finished inside its six steps and the supervisor kept starting new ones. The next guard belongs on the router: a limit on how many times one turn may hand the same charter the same kind of task. Every contract a substitute can break silently needs a check in code at the handoff where it would break.

The single agent’s graph already did this for tool failures, and it is the same idea. A failing tool returns a string that starts with TOOL_ERROR:, and the graph routes on that prefix instead of parsing prose. When a user denies a tool call, the result tells the model the call did not run and what to tell the user, worded hard on purpose: with a softer “Rejected by the user.”, llama3.1:8b reported the delete as successful anyway. A small model fills any gap you leave in a result, so the result has to state the outcome and the reply.

KISS: where the clean design lost

I ran six tasks through both designs, three repeats each, on K2 Horizon 7B, and graded the final answer for the expected number.

Model calls are the median of three. Both designs got 16 of 18 right. The supervisor needed more calls on every task, and more input tokens on five of the six.

Every handoff is a model call. Routing is not free. A supervisor turn is at least three calls: one to choose a specialist, one for the specialist, one to write the answer. That holds even when the request needs no specialist at all. “Greet me in exactly one word” went through the router, out to a specialist and back, three calls for a word the single agent produced in one. No prompt fixes this. Deciding that a turn is trivial is itself a routing decision, and a routing decision is a call.

Every handoff is a write the router may repeat. On the three-tool task the supervisor beat the single agent, 3 of 3 against 2 of 3. It also called remember_fact twice in every one of those runs: it routed to the archivist, got a confirmation, then routed the same instruction again while assembling the answer. The store holds the fact under two ids, the sentence to the user is correct, and a suite that grades answers never sees it. Once a router sits in front of a write, that write has to be idempotent, because the router will retry it for reasons that have nothing to do with the write.

The split earns its keep where state crosses the handoff. The one place the supervisor clearly paid was isolation. The report the librarian read never entered the router’s context, so later turns on the same thread stayed small and the router had nothing to be distracted by. That is the shape Anthropic describes for their research system, where subagents explore and return a condensed summary. It is also the shape OpenAI’s guide points at when it says the problem with many tools “isn’t solely the number of tools, but their similarity or overlap”: split when one set of tools pollutes the context or the decisions of the others.

My tools return numbers and filenames. For tools like these, the single agent is the right design, with fewer tools and a sharper prompt. Four specialists, a router and a contract per handoff bought the same accuracy and three new failure modes. The principles were still worth applying, because they told me where the boundaries would go and what each handoff had to promise. KISS told me not to split along them yet.

Frequently Asked Questions

Closing

I have watched a four-agent system spend three model calls to say “Hello”. I have watched the same system answer a three-part question correctly in every run while writing the same fact into the store twice, and a 3B model loop until the graph gave up. All three are the decomposition working as designed. At every handoff one model summarizes another’s work in prose, and the transcript reads clean whether the summary was right or not.

What I would keep is the order. Write the charters first, even for a single agent, because they are where the refusals live. Put every promise a model might break in code at the handoff. Then split only when a measurement says the split pays.

Next in this thread is grading the handoffs themselves: a trajectory grader that fails a run where the router did the arithmetic, or stored the same fact twice, even when the final sentence to the user is perfect. Correct answers from broken dispatch are the regressions a suite score cannot see, the same problem I hit when I started measuring this agent at all.

If you are splitting an agent and want to argue about where the boundaries go, find me on X at @matiasdev_ or by email.