Skip to content

Add capabilities

Agent messaging

Peer messaging sends typed input to an independent Agent Thread. The destination owns its input Schema; your host chooses the route and authorizes the sender. Use background subagents when the sender also owns the recipient’s creation and lifetime.

import {
import Agent
Agent
,
import Messaging
Messaging
} from "@yielded/agent";
import {
import Schema
Schema
} from "effect";
import {
import Toolkit
Toolkit
} from "effect/ai";
const
const advisor: Agent.Definition<Schema.String, Schema.String, "Suggest one next action for the request.", Toolkit.Toolkit<{}>, undefined, undefined, undefined> & {
readonly id: Brand<"@effect-agent/core/AgentId"> & "advisor";
}
advisor
=
import Agent
Agent
.
function make<"advisor", Schema.String, Schema.String, "Suggest one next action for the request.", Toolkit.Toolkit<{}>, undefined>(id: "advisor", options: Agent.DefinitionOptions<Schema.String, Schema.String, "Suggest one next action for the request.", Toolkit.Toolkit<{}>, undefined, undefined, undefined> & {
readonly inputPrompt?: undefined;
readonly runDisposition?: undefined;
}): Agent.Definition<Schema.String, Schema.String, "Suggest one next action for the request.", Toolkit.Toolkit<...>, undefined, undefined, undefined> & {
...;
} (+3 overloads)

Validate an agent ID and return a shallowly frozen, model-agnostic definition.

make
("advisor", {
DefinitionOptions<String, String, "Suggest one next action for the request.", Toolkit<{}>, undefined, undefined, undefined>.input: Schema.String
input
:
import Schema
Schema
.
const String: Schema.String

Type-level representation of

String

.

Schema for string values. Validates that the input is typeof "string".

@stability ― stable

@category ― models

@since ― 4.0.0

@stability ― stable

@category ― schemas

@since ― 4.0.0

String
,
DefinitionOptions<String, String, "Suggest one next action for the request.", Toolkit<{}>, undefined, undefined, undefined>.output: Schema.String
output
:
import Schema
Schema
.
const String: Schema.String

Type-level representation of

String

.

Schema for string values. Validates that the input is typeof "string".

@stability ― stable

@category ― models

@since ― 4.0.0

@stability ― stable

@category ― schemas

@since ― 4.0.0

String
,
DefinitionOptions<String, String, "Suggest one next action for the request.", Toolkit<{}>, undefined, undefined, undefined>.instructions: "Suggest one next action for the request."
instructions
: "Suggest one next action for the request.",
DefinitionOptions<String, String, "Suggest one next action for the request.", Toolkit<{}>, undefined, undefined, undefined>.toolkit: Toolkit.Toolkit<{}>
toolkit
:
import Toolkit
Toolkit
.
const empty: Toolkit.Toolkit<{}>

An empty toolkit with no tools.

When to use

Use when you need an empty starting point for building toolkits or a default toolkit value that can be extended with merge.

@stability ― unstable

@category ― constructors

@since ― 4.0.0

empty
,
});
const
const Advisor: Messaging.Peer<"advisor", Schema.String>
Advisor
=
import Messaging
Messaging
.
const peer: <"advisor", Schema.String>(name: "advisor", options: {
readonly target: AnyDefinitionShape & {
readonly input: Schema.String;
};
}) => Messaging.Peer<"advisor", Schema.String>
peer
("advisor", {
target: AnyDefinitionShape & {
readonly input: Schema.String;
}
target
:
const advisor: Agent.Definition<Schema.String, Schema.String, "Suggest one next action for the request.", Toolkit.Toolkit<{}>, undefined, undefined, undefined> & {
readonly id: Brand<"@effect-agent/core/AgentId"> & "advisor";
}
advisor
});
const
const send: {
tool: Tool<"advisor_send", {
readonly parameters: Schema.Top & Schema.String;
readonly success: Schema.Union<readonly [Schema.Struct<{
readonly status: Schema.Literal<"pending">;
readonly receipt: Schema.Null;
readonly settlement: Schema.Null;
readonly reason: Schema.NullOr<Schema.NonEmptyString>;
readonly message: Schema.Struct<{
readonly ownerThreadId: Schema.brand<Schema.NonEmptyString, "@effect-agent/core/ThreadId">;
readonly messageId: Schema.brand<Schema.NonEmptyString, "@effect-agent/thread/IdempotencyKey">;
}>;
}>, Schema.Struct<...>, Schema.Struct<...>, Schema.Struct<...>, Schema.Struct<...>]>;
readonly failure: typeof Messaging.MessagingError;
readonly failureMode: "error";
}, MessagingHost | Digest>;
toolkit: Toolkit.Toolkit<...>;
layer: Layer<...>;
}
send
=
import Messaging
Messaging
.
const sendTool: <"advisor", Schema.String>(declaration: Messaging.Peer<"advisor", Schema.String>) => {
tool: Tool<"advisor_send", {
readonly parameters: Schema.Top & Schema.String;
readonly success: Schema.Union<readonly [Schema.Struct<{
readonly status: Schema.Literal<"pending">;
readonly receipt: Schema.Null;
readonly settlement: Schema.Null;
readonly reason: Schema.NullOr<Schema.NonEmptyString>;
readonly message: Schema.Struct<{
readonly ownerThreadId: Schema.brand<Schema.NonEmptyString, "@effect-agent/core/ThreadId">;
readonly messageId: Schema.brand<...>;
}>;
}>, Schema.Struct<...>, Schema.Struct<...>, Schema.Struct<...>, Schema.Struct<...>]>;
readonly failure: typeof Messaging.MessagingError;
readonly failureMode: "error";
}, MessagingHost | Digest>;
toolkit: Toolkit.Toolkit<...>;
layer: Layer<...>;
}

Install only the native operations chosen by the host; schemas come from the Peer declaration.

sendTool
(
const Advisor: Messaging.Peer<"advisor", Schema.String>
Advisor
);

Give the sending Agent send.toolkit and provide send.layer. Register the destination, then configure PeerRoutes and PeerAuthorizer on the durable host. Both deny by default. A model chooses the input, never an arbitrary Thread address or principal.

For application code, acquire runtime.messagingHost({ sourceThreadId, principal }) and provide it to Messaging.send. Supply a stable idempotencyKey; retries must retain the same input.

The host pairs canonical history and message delivery storage on the same backend. A send commits its source proof and pending delivery together; capacity rejection commits neither.

Status What it proves
pending The source retained outbound work
accepted The destination admitted it and returned a receipt
processed The destination recorded its settlement
parked Automatic retries stopped; authorized intervention is needed
refused Delivery was conclusively refused

A retained message reference is not a submission receipt, and acceptance is not execution. Use Messaging.inspect on the same reference. Messaging.retry renews a parked delivery’s bounded retry allowance without changing its frozen destination, principal, or input. It cannot rewind processed or conclusively refused work.

The default delivery policy permits eight attempts with a 30-second attempt timeout and a 24-hour peer deadline. PeerMessageCapacity defaults to 256 per source Thread (maximum 1,000), counting outstanding sends, including parked work, and settled sends until their last delivery deadline. Settled sends stop counting after that deadline; exact receipts and append-only history remain available.

Messaging.inbox returns authenticated inbound references. Messaging.reply uses one of those references and rechecks send authority. Receiving a message does not grant permission to reply; inReplyTo on a send is correlation only. Peer routes cannot bypass worker admission rules.

Node’s scoped delivery pump and Cloudflare maintenance recover retained deliveries after restart. They need a functioning host and available capacity. Child completion, report delivery, and the parent’s response remain separate outcomes.

See the Cloudflare application for a runnable host, and operations for observing and controlling accepted work.