Communication between agents
In the Open Engineering Language, every edge is a typed, two-way channel: the Compiler generates the communication between nodes, agents and subagents from your edge declarations, with no client or server code for you to write. This page describes the channel that Compiler 1.0.0 generates for every edge, where it runs and what can reach it. Agents, nodes and edges introduces edges, and Workflows describes their modes and delivery.
Every edge is a two-way channel
An edge carries a value from one component to another, and carries the reply back over the same edge. Both directions are typed, and the check refuses a type that does not match in either direction before anything is sent.
You declare the edge in its own file and connect it in the agent that uses it. From those declarations the Compiler generates the communication on every path a workflow uses:
| Between | Through |
|---|---|
| Two nodes | An edge that their agent connects between them. |
| A node and an agent | An edge to the agent's public, typed inputs and outputs. The agent's private nodes stay out of reach. |
| Two agents | An edge between their public, typed inputs and outputs. |
| An agent and a subagent it spawns | The link between them, which needs no edge of yours: it carries the subagent's typed parameters to it and its typed result back. |
You write no client or server code for any of them, and no code that turns their values into messages.
Modes, delivery and callbacks on both sides
An edge's mode, delivery and callbacks keep their meaning on both sides of the channel:
- Event: the sending side learns only whether the value was accepted, and nothing comes back.
- Request and reply: the sending side gets one result or one typed error for its request, within the edge's finite deadline. A late or duplicate reply completes nothing a second time.
- Callback: the reply comes back over the channel to the handler you name in the edge's file.
- Stream: a bounded sequence travels under backpressure, and ends with an explicit end, error or cancellation.
- Delivery: at most once or at least once, the order, the queue capacity and the idempotency key are declared once, on the edge, and hold on both sides. At least once applies to event edges, where each send carries an idempotency key and a key that arrives again is acknowledged and not queued again; a request is answered by exactly one reply and a stream is ordered, so neither is delivered again. Exactly once does not exist.
Workflows describes each mode and the delivery settings.
One edge, wherever it runs
The same edge runs in one process, between processes or over the network, as your deployment places it, with no change to your source. One delivery contract holds in all three: the types, the mode, the deadline and the delivery rules stay the same, and only the transport changes.
Placement belongs to the deployment, not to the edge, as it does for the services your code calls: code calls a typed service, and the deployment decides whether it runs in the same process, on another machine, over HTTPS or over gRPC (see Tools and MCP). Declaring an edge opens no port by itself.
The deployment gives every mounted edge exactly one placement, in the same process by default. A placement names an address for a network edge, and the Compiler refuses an unknown, twice-placed or unmounted edge by name, a stale deployment or a changed interface before anything is started or dialed, and a placement over the network that leaves the machine without naming a TLS identity or being declared insecure. An edge that reaches an isolated component is always placed between processes.
Over the network
Over the network, an edge uses the built-in gRPC-compatible transport with TLS.
- Built in. You add no package for it. The transport joins your program only when an edge placed on the network is reachable, so a program whose edges all stay off the network carries no network transport for them.
- TLS. Every connection an edge makes between machines uses TLS, and a placement that names a TLS identity is never downgraded to plaintext: if no TLS binding is available for it, the edge is refused as unavailable. A plaintext connection exists only on the loopback interface of one machine, or when you declare the placement insecure on purpose, and the deployment says so.
- The caller stays trusted. The tenant and the caller's identity travel with each call, apart from the values your code sends, so nothing in a value can change them.
- No secrets travel. A call carries no credentials of the sending side: the receiving side uses its own.
- Your own gRPC services. A gRPC service that you design yourself, for outside clients, uses the
server/grpcpackage, as Services and APIs shows. The built-in transport carries your edges.
What your code calls on a channel
A node reaches the channel of an edge through the port the edge mounts on it: the port's name is the channel's identifier, the edge gives the channel its types and its mode, and the agent that lists both nodes and the edge mounts the channel. Here requester asks over the port review and reviewer answers over its own port of the same name:
# src/reviewer.node.oel
node reviewer(input: Str<256>) -> Str<256> {
config {
id: "reviewer"; version: "1.0.0"; policy: { kind: "deterministic"; entry: "reviewer"; };
ports: [{ id: "review"; direction: "input"; schema_type: "String<256>"; modalities: ["text"]; min_count: 1; max_count: 1; max_bytes: 256; join: "all"; },
{ id: "result"; direction: "output"; schema_type: "String<256>"; modalities: ["text"]; min_count: 1; max_count: 1; max_bytes: 256; join: "all"; }];
limits: { ram_bytes: 1048576; cpu_millicores: 1000; cpu_millis: 1000; duration_ms: 5000; input_tokens: 0; output_tokens: 0;
model_calls: 0; tool_calls: 0; steps: 16; concurrency: 1; max_children: 0; max_depth: 0; queue_items: 1; queued_bytes: 65536;
stream_bytes_per_second: 0; storage_bytes: 0; connections: 0; cost_microunits: 0; };
authority: []; profile: "host"; state_domain: "request"; capabilities: []; tools: []; assets: [];
prompt: null; prompt_variables: null; binding: null; binding_capability_revision: null;
}
let request: Str<256> = recv("review");
reply("review", request);
return "";
}
The asking side is another node; the edge between them and the agent that mounts both complete the project:
# src/requester.node.oel
node requester(input: Str<256>) -> Str<256> {
config {
id: "requester"; version: "1.0.0"; policy: { kind: "deterministic"; entry: "requester"; };
ports: [{ id: "request"; direction: "input"; schema_type: "String<256>"; modalities: ["text"]; min_count: 1; max_count: 1; max_bytes: 256; join: "all"; },
{ id: "review"; direction: "output"; schema_type: "String<256>"; modalities: ["text"]; min_count: 1; max_count: 1; max_bytes: 256; join: "all"; }];
limits: { ram_bytes: 1048576; cpu_millicores: 1000; cpu_millis: 1000; duration_ms: 5000; input_tokens: 0; output_tokens: 0;
model_calls: 0; tool_calls: 0; steps: 16; concurrency: 1; max_children: 0; max_depth: 0; queue_items: 1; queued_bytes: 65536;
stream_bytes_per_second: 0; storage_bytes: 0; connections: 0; cost_microunits: 0; };
authority: []; profile: "host"; state_domain: "request"; capabilities: []; tools: []; assets: [];
prompt: null; prompt_variables: null; binding: null; binding_capability_revision: null;
}
let answer: Str<256> = ask("review", input);
return answer;
}
# src/review_request.edge.oel
edge review_request(input: Str<256>) -> Str<256> {
config {
id: "review_request";
from: { instance: "requester"; port: "review"; };
to: { instance: "reviewer"; port: "review"; };
mode: "request"; deadline_ms: 5000;
}
return input;
}
# src/desk.agent.oel
agent desk(input: Str<256>) -> Str<256> {
config {
id: "desk"; version: "1.0.0";
ports: [
{ id: "request"; direction: "input"; schema_type: "String<256>";
modalities: ["text"]; min_count: 1; max_count: 1;
max_bytes: 256; join: "all"; },
{ id: "result"; direction: "output"; schema_type: "String<256>";
modalities: ["text"]; min_count: 1; max_count: 1;
max_bytes: 256; join: "all"; }
];
limits: {
ram_bytes: 33554432; cpu_millicores: 1000; cpu_millis: 8000;
duration_ms: 120000; input_tokens: 0; output_tokens: 0;
model_calls: 0; tool_calls: 0; steps: 10000; concurrency: 2;
max_children: 2; max_depth: 2; queue_items: 1; queued_bytes: 65536;
stream_bytes_per_second: 0; storage_bytes: 0; connections: 0;
cost_microunits: 0;
};
authority: []; capabilities: []; profile: "host"; state_domain: "request";
nodes: [{ id: "requester"; source: "src/requester.node.oel"; }, { id: "reviewer"; source: "src/reviewer.node.oel"; }];
agents: []; edges: ["src/review_request.edge.oel"]; starts: ["requester"];
inputs: [{ port: "request"; to: { instance: "requester"; port: "request"; }; }];
dispatch: "sequential";
completion: { kind: "all"; result: { instance: "reviewer"; port: "result"; }; };
}
}
The operations are generated from the edge. The identifier of the channel is written in the call as a string literal, for example recv("review"), and is never computed at run time:
| Operation | What it does | Modes |
|---|---|---|
ask("channel", value) | Sends a request and returns its one reply, or a typed error. | Request, asking side |
recv("channel") | Takes the next value, or returns a typed error. | Request and event, receiving side; either direction of a stream |
reply("channel", value) | Answers the request it received, once. | Request, answering side |
send("channel", value) and try_send("channel", value) | Sends a value; try_send never waits for room and returns the value with the error when it is refused. At least once edges take an idempotency key as a third argument. | Event; either direction of a stream |
open("channel") | Checks that a stream direction is ready, without sending anything. | Stream |
recv_next("channel") | Takes the next element, or returns that the stream has ended. | Stream |
half_close("channel") | Ends this side's direction of a stream after the queued elements are delivered. | Stream |
The check follows the real flow of your code and refuses a reply on an event edge, a second reply on one path, a channel that is declared and never used, a mode that differs from the edge, a type that differs in either direction, two producers on one channel, an at-least-once send without an idempotency key and a cycle with no declared bound.
At run time every send is bounded by the queue and credits the edge declares. A full queue is refused as full and nothing is retried. The reply slot of a request is reserved before the request is queued, so a delivered request always has room for its one reply. A request that passes its deadline is never delivered and its slot becomes a tombstone as expired; a canceled request and a closed channel leave tombstones too, and a late reply to a tombstone is refused and dropped, never delivered to a caller that has moved on. A closed channel refuses later sends, and a half-closed one still delivers what is queued.
Services built elsewhere call in
Services built elsewhere call your agents over gRPC, because each network edge publishes its interface in gRPC's standard interface-definition format. A service that another team builds, outside your project, uses that interface to call your agent through the edge, with the edge's types, mode and deadline.
Isolated components
You mark an agent, node or subagent as isolated: it always runs in a sandbox in its own process, outside the shared communication layer, reachable only through the edges you declare and holding only the resources it declares itself. Isolation needs the isolation facilities of Linux and runs only on the Linux target the documentation names for it: on macOS, on Windows, on microcontroller boards, on other Linux targets and on any host without those facilities, an isolated component is refused, never run without isolation.
For communication, this means:
- Only the edges you declare to an isolated component reach it. No other component can call it or send it a value.
- Its edges are always placed between processes: the check refuses a placement of them in the same process or over the network.
- An edge to an isolated component carries values only, never a storage handle, a file or a descriptor.
- An isolated component makes no model or tool call itself: it reaches one through a declared edge to a node that is not isolated.
Isolated components describes the isolated modifier.
Subagents and the agent that spawned them
An agent spawns subagents at run time: short-lived agents that each do one task, return a typed result to the agent that spawned them and end, leaving nothing running. The link between a subagent and the agent that spawned it is generated like every channel: the subagent's typed parameters go one way, its typed result comes back, and nothing of the link stays open once the subagent ends. Subagents describes spawning.
Honest limits
- Microcontroller boards carry no network transport for edges, so on them an edge is never placed on the network.
- When a network connection drops after a value was sent, the outcome is reported as uncertain, and the value is never sent again blindly.
- Support for native gRPC clients does not imply support for gRPC from web browsers.
- This page states no latency, throughput or message-size figures; measure your own program on your own platform.
Related
- Workflows: starting points, edge modes, delivery, callbacks and triggers.
- Teams of agents: supervisors, delegation, placement and remote agents over A2A.
- Subagents: agents spawned at run time for one task.
- Isolated components: components that run in a sandbox, reachable only through their edges.
- Bindings and storage: the memory, skills, knowledge, storage and databases a component declares.
- Services and APIs: HTTP, gRPC, WebSocket and MCP services of your own design.