AI agent system: orchestration, separation of roles and boundaries

What does this solve?

System AI-agents appears when one agent becomes overwhelmed: there are dozens of tools, the system instructions have grown into pages, the context is filled with other people’s data, and a failure in one place spoils the entire task. Separation eliminates four specific pain points: tool selection conflicts, window overflow, write permission confusion, and the inability to understand at what step everything went wrong. Instead, seams appear: each joint between agents must be described by a contract, otherwise the system turns into a damaged telephone with an increased bill for tokens.

How it works

Topologies

Supervisor and performers. The main agent parses the task and calls the subordinates like ordinary tools: name, arguments, result. The subordinate does not know about the existence of neighbors and receives only a snippet of context. Flexible, more expensive than all other options, harder to predict the trajectory.

Conveyor. Fixed order of roles, each receives a result from the previous one in a specified pattern: extract → check → write. Cheap, predictable, easy to debug. It's smart to start from here.

Event bus. Agents are subscribed to events and write results back to the queue. Suitable for long asynchronous processes where steps are spread out over time and participants change.

Generator and critic. One does the work, the second checks it in a pure context, without seeing the reasoning of the first. Isolation of context is the whole point here: the critic, who has been shown the author's train of thought, agrees with him.

On which axes to divide the roles

Three features, each of which justifies the identification of a separate agent:

Tools. Sets interfere with each other - the model confuses similar functions from different domains.
Data. One needs raw outputs, the other needs compressed outputs. Keeping both in one window is wasteful.
Rights. One reads from anywhere, the second writes to the combat system. Separation by rights turns into separation by agents automatically.

The rest of the reasons (looks nice on the diagram, “let there be a team of specialists”) cost money and do not give anything.

Boundaries

Entry and Exit Contract — JSON Schema, not a request to “retell the result.” A free retelling loses margins and adds fictitious ones.
Context isolation. The subordinate receives the cuttings needed for his task and nothing more.
Shared memory - external. File, table, database accessed by both agents. The transfer of knowledge by text through prompts degrades at every transition.
Budget for the subtask. Own max_steps and a limit of tokens on each node, otherwise one loopy executor eats up the budget of the entire system.
Deadline and timeout behavior. What is returned to the top if the slave does not respond: partial result, error, default value.
Through trace_id. One task ID is included in all log entries on all nodes.
Anti-cycling. Counter of repeated calls to one role and prohibition of circular calls.
The only writer. One node has the right to write to each system; the rest generate data for it.

Price

Each agent runs its own history through the model. Random launch of dozens of parallel agents for a simple operation of the same type - marking, classification, field extraction - burns up the budget where a batch of several elements in one request to a simpler model could handle it. The complexity of the ligament is justified when the knots are made various work.

Rule: A role is allocated to a separate agent only when two cases in one conflict in terms of tools, rights or context.

How to connect

Step 1. Start with one agent and bring it to working condition. A system of two bad agents works worse than one bad one.

Step 2. Wait for the conflict. Signs for highlighting a role: the model regularly takes the wrong tool from similar ones; the window is full of raw data; some operations require rights that you do not want to give to the entire agent; pieces of the task proceed in different rhythms (one step is instantaneous, the other lasts minutes).

Step 3. Describe the contract. For each role, an entry schema and an exit schema, both validated by code at the boundary. A response that does not pass validation is returned to the author with an error text, rather than going further down the chain.

Step 4. Select topology. Pipeline, it has not yet been proven that a supervisor is needed. The order of roles is described in the orchestrator code, not in the prompt.

Step 5. General journal. One table for all nodes: trace_id, agent, step, tool, arguments, truncated result, tokens, duration. Without a common table, analyzing a failure turns into comparing disparate logs over time.

Step 6. Limiters on each node. Steps, tokens, timeout, allowlist of tools for a specific role.

Step 7. Aggregator with conflict resolution rule. When two nodes returned incompatible responses, the decision is made by the code according to an explicit rule (source priority, data freshness, transfer to a person), rather than a third “think” model.

Step 8. Ascending rights. At first, all slaves only read, the only writer is the head node with confirmation. Extension of rights occurs in one operation.

Step 9. Run on the set. Same gold pack as the Single Agent to keep the comparison fair.

Useful scripts

Processing of the incoming stream: the classifier determines the type, the profile agent prepares a response, the sender checks the addressee and sends.
Working with code: the scheduler parses the task, the executor edits the files, the reviewer reads the differential in a pure context.
Regular report: source collectors work in parallel, the collating agent collects a single document.
Support: the conversational agent speaks to the client, the search agent retrieves facts from the knowledge base, the escalator decides when to call the person.
On duty: a scheduled observer catches an anomaly, a diagnostician collects context, a person receives a ready-made summary.
Data migration: the extractor reads the source, the validator checks according to the scheme, the loader writes with a preliminary empty run.

Limitations

Delay and cost add up along the entire chain, and with a fan-based launch they are multiplied. A system of five nodes responds noticeably longer than a single agent on the same task.

Reliability is multiplied. If each node succeeds in nine cases out of ten, a chain of four nodes reaches the end much less often - arithmetic is merciless, and it is cured by reducing the number of nodes, and not by persuasion in the prompt.

Debugging is more complicated by an order of magnitude: the failure appears on the last node, and the reason lies in the incomplete cutting of the context on the first. Without end-to-end tracing, such cases cannot be dealt with.

Retelling loses data. Any transition where free text is used instead of a diagram accumulates distortions from node to node.

The rules are spreading. Two agents with independent instructions begin to interpret the same situation differently over time; a common source of rules is required.

Racing for a shared resource produces duplicates: two nodes with write access will create two records for the same event. A single writer and an idempotency key close this.

The temptation to divide early is the most common mistake. Splitting adds seams, and each seam must be maintained.

How to check the result

Take one task and read its end-to-end trace using trace_id from entry to final: who called whom, with what arguments, how many steps and tokens each node spent. If the trace is not readable within a couple of minutes, the log will have to be repaired before the system itself.

Next are the numbers for the set of runs:

proportion of tasks that reached completion without intervention;
distribution of failures across nodes: which node drops the chain more often than others;
The share of subordinate responses that did not pass the schema validation is a direct measure of the quality of contracts;
total tokens and time per task versus the same numbers for a single agent on the same set;
number of repeated starts of one role - a sign of cycling;
check for duplicates: compare the number of records in the target system with the number of processed cases.

Separate test - intentional failure. Turn off one slave node and see what the system returns: a clear error indicating the location, a partial result, or a freeze until the timeout occurs. The answer to this question shows whether the team is ready for battle better than any runs along the happy path.