Skip to content

Build an agent

Agent definitions

An Agent Definition is reusable behavior: input and output schemas, instructions, tools, and policy. It owns no conversation, provider connection, or database. Your application supplies those services when the definition runs.

import {
import Agent
Agent
,
import AgentRuntime
AgentRuntime
} from "@yielded/agent";
import {
import Schema
Schema
} from "effect";
import {
import Toolkit
Toolkit
} from "effect/ai";
const
const triage: Agent.Definition<Schema.String, Schema.Struct<{
readonly severity: Schema.Literals<readonly ["low", "medium", "high", "critical"]>;
readonly explanation: Schema.String;
}>, "Classify the bug report and explain the severity in one sentence.", Toolkit.Toolkit<{}>, undefined, undefined, undefined> & {
readonly id: Brand<"@effect-agent/core/AgentId"> & "triage";
}
triage
=
import Agent
Agent
.
function make<"triage", Schema.String, Schema.Struct<{
readonly severity: Schema.Literals<readonly ["low", "medium", "high", "critical"]>;
readonly explanation: Schema.String;
}>, "Classify the bug report and explain the severity in one sentence.", Toolkit.Toolkit<{}>, undefined>(id: "triage", options: Agent.DefinitionOptions<Schema.String, Schema.Struct<{
readonly severity: Schema.Literals<readonly ["low", "medium", "high", "critical"]>;
readonly explanation: Schema.String;
}>, "Classify the bug report and explain the severity in one sentence.", Toolkit.Toolkit<...>, undefined, undefined, undefined> & {
...;
}): Agent.Definition<...> & {
...;
} (+3 overloads)

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

make
("triage", {
DefinitionOptions<String, Struct<{ readonly severity: Literals<readonly ["low", "medium", "high", "critical"]>; readonly explanation: String; }>, "Classify the bug report and explain the severity in one sentence.", 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, Struct<{ readonly severity: Literals<readonly ["low", "medium", "high", "critical"]>; readonly explanation: String; }>, "Classify the bug report and explain the severity in one sentence.", Toolkit<...>, undefined, undefined, undefined>.output: Schema.Struct<{
readonly severity: Schema.Literals<readonly ["low", "medium", "high", "critical"]>;
readonly explanation: Schema.String;
}>
output
:
import Schema
Schema
.
function Struct<{
readonly severity: Schema.Literals<readonly ["low", "medium", "high", "critical"]>;
readonly explanation: Schema.String;
}>(fields: {
readonly severity: Schema.Literals<readonly ["low", "medium", "high", "critical"]>;
readonly explanation: Schema.String;
}): Schema.Struct<{
readonly severity: Schema.Literals<readonly ["low", "medium", "high", "critical"]>;
readonly explanation: Schema.String;
}>

Defines a struct schema from a map of field schemas.

Details

Each field value is a schema. Use

optionalKey

or

optional

to mark fields as optional, and

mutableKey

to mark them as mutable.

The resulting schema's Type is a readonly object type with the fields' decoded types. The Encoded form mirrors the field schemas' encoded types. Declared fields may be inherited and are copied to own properties in the output. The __proto__ field is accepted only when it is an own property. Parsing does not guarantee that output keys retain their input order.

Example (Defining a basic struct)

import { Schema } from "effect"
const Person = Schema.Struct({
name: Schema.String,
age: Schema.Number,
email: Schema.optionalKey(Schema.String)
})
// { readonly name: string; readonly age: number; readonly email?: string }
type Person = typeof Person.Type
Schema.decodeUnknownSync(Person)({ name: "Alice", age: 30 }) // => { name: "Alice", age: 30 }

@stability ― stable

@category ― constructors

@since ― 3.10.0

Struct
({
severity: Schema.Literals<readonly ["low", "medium", "high", "critical"]>
severity
:
import Schema
Schema
.
function Literals<readonly ["low", "medium", "high", "critical"]>(literals: readonly ["low", "medium", "high", "critical"]): Schema.Literals<readonly ["low", "medium", "high", "critical"]>

Creates a union schema from an array of literal values.

Example (Defining status codes)

import { Schema } from "effect"
const schema = Schema.Literals(["active", "inactive", "pending"])
Schema.decodeSync(schema)("active") // => "active"

@see ― Literal for a schema that represents a single literal.

@stability ― stable

@category ― constructors

@since ― 4.0.0

Literals
(["low", "medium", "high", "critical"]),
explanation: Schema.String
explanation
:
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, Struct<{ readonly severity: Literals<readonly ["low", "medium", "high", "critical"]>; readonly explanation: String; }>, "Classify the bug report and explain the severity in one sentence.", Toolkit<...>, undefined, undefined, undefined>.instructions: "Classify the bug report and explain the severity in one sentence."
instructions
: "Classify the bug report and explain the severity in one sentence.",
DefinitionOptions<String, Struct<{ readonly severity: Literals<readonly ["low", "medium", "high", "critical"]>; readonly explanation: String; }>, "Classify the bug report and explain the severity in one sentence.", 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
,
DefinitionOptions<String, Struct<{ readonly severity: Literals<readonly ["low", "medium", "high", "critical"]>; readonly explanation: String; }>, "Classify the bug report and explain the severity in one sentence.", Toolkit<...>, undefined, undefined, undefined>.policy?: Partial<Readonly<Omit<{
readonly runStatus: "appended" | "off";
readonly maxTurns: number;
readonly maxToolCalls: number;
readonly maxDuration: Duration;
readonly toolConcurrency: number;
readonly repeatedFailureLimit: number;
readonly onExhaustion: "final-answer" | "fail";
readonly completionReserveTokens: number;
readonly toolResultBounds: ToolResultBounds;
readonly compaction: CompactionPolicy;
readonly tokenBudget?: number | undefined;
readonly costBudgetMicrousd?: number | undefined;
readonly contextTokenLimit?: number | undefined;
readonly restartOnJoinedInput?: boolean | undefined;
readonly modelRetries?: number | undefined;
}, "runStatus" | ... 7 more ... | "compaction"> & {
...;
}>> | undefined
policy
: {
maxTurns?: number | null | undefined

Maximum model turns, or null to leave turn count unbounded.

maxTurns
: 2,
maxToolCalls?: number | null | undefined

Maximum declared and programmatic Tool Calls, or null to leave count unbounded.

maxToolCalls
: 1,
maxDuration?: Input | undefined

Finite, positive wall-clock duration accepted in any Effect Duration input form.

maxDuration
: "30 seconds" },
});
const
const result: Effect<{
readonly finishReason: "completed" | "model-stop" | "budget-exhausted";
readonly turns: number;
readonly output: {
readonly severity: "low" | "medium" | "high" | "critical";
readonly explanation: string;
};
readonly threadId: string & Brand<"@effect-agent/core/ThreadId">;
readonly runId: string & Brand<"@effect-agent/core/RunId">;
readonly exhausted?: "tokens" | "tool-calls" | "turns" | undefined;
readonly runDisposition?: Schema.Json | undefined;
readonly usage?: RunTotals | undefined;
readonly delegatedUsage?: RunTotals | undefined;
}, AgentRuntime.AgentRuntimeFailure<...>, AgentRuntime.AgentRuntimeRequirements<...>>
result
=
import AgentRuntime
AgentRuntime
.
const run: <Agent.Definition<Schema.String, Schema.Struct<{
readonly severity: Schema.Literals<readonly ["low", "medium", "high", "critical"]>;
readonly explanation: Schema.String;
}>, "Classify the bug report and explain the severity in one sentence.", Toolkit.Toolkit<{}>, undefined, undefined, undefined> & {
readonly id: Brand<"@effect-agent/core/AgentId"> & "triage";
}, never, never>(agent: Agent.Definition<Schema.String, Schema.Struct<{
readonly severity: Schema.Literals<readonly ["low", "medium", "high", "critical"]>;
readonly explanation: Schema.String;
}>, ... 4 more ..., undefined> & {
readonly id: Brand<"@effect-agent/core/AgentId"> & "triage";
}, input: string, options?: RunOptions<...> | undefined) => Effect<...>

Accept schema-encoded input, retaining runtime validation.

run
(
const triage: Agent.Definition<Schema.String, Schema.Struct<{
readonly severity: Schema.Literals<readonly ["low", "medium", "high", "critical"]>;
readonly explanation: Schema.String;
}>, "Classify the bug report and explain the severity in one sentence.", Toolkit.Toolkit<{}>, undefined, undefined, undefined> & {
readonly id: Brand<"@effect-agent/core/AgentId"> & "triage";
}
triage
, "Users cannot sign in.");

result is an Effect. The getting-started example supplies its model and history services and runs it. One definition can serve many Threads.

Field Purpose
ID Stable Agent identity; keep it independent of deployments
input / output Effect Schemas for accepted input and validated final output
instructions Static instructions or a function of decoded input; may return an Effect
toolkit Native Effect AI tools with application-provided handlers
policy Execution limits; omitted values use defaults
inputPrompt Optional projection controlling what input reaches the model
completion Designated tool required for final output when configured
updates Schema for intentional intermediate findings
runDisposition Schema and selector for ordinary completed output; omitted on budget exhaustion

Final output is schema-validated JSON by default. Use Output.text(Schema.String) for an ordinary text reply. To require a final tool, set completion: { tool, project }. The Agent must then complete through that tool; assistant text cannot complete the Run.

project receives the tool’s { parameters, result } and returns the Agent’s output. It must be pure and deterministic because recovery may reevaluate recorded results. The completion tool must be the sole application call in its batch.

Effect AI model Layers provide generation and provider/model identity. Supply them through Effect.provide, or use Agent.withModel to create an explicit Binding. A Binding pairs behavior with model selection; it still acquires no resources and leaves client requirements visible. Tool handlers, storage, and provider clients belong in the application Layer.

Durable hosts register a current Binding under the stable Agent ID. Pending operations retain their original replay contracts. Declare tool replay versions accurately when handler behavior changes; missing or incompatible bindings leave accepted work owed. See durability and the package reference.

Typed entry points accept the input Schema’s encoded type; instruction functions receive its decoded type. Use runUnknown, streamUnknown, or startUnknown at an untrusted input boundary. Invalid input fails before model execution.

inputPrompt changes model disclosure only. Durable admission still retains complete input, and authorization receives it. Projection failure never falls back to sending the full value. Keep credentials in host services and separately control tool results, history, and retrieved context.

For a complete application with tools and a durable host, see the travel planner.