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.
}>,"Classify the bug report and explain the severity in one sentence.",Toolkit.Toolkit<{}>,undefined>(id:"triage",options:Agent.DefinitionOptions<Schema.String,Schema.Struct<{
}>,"Classify the bug report and explain the severity in one sentence.",Toolkit.Toolkit<...>,undefined,undefined,undefined>&{
...;
}):Agent.Definition<...>&{
...;
}(+3overloads)
Validate an agent ID and return a shallowly frozen, model-agnostic definition.
make("triage",{
DefinitionOptions<String,Struct<{ readonlyseverity:Literals<readonly ["low","medium","high","critical"]>;readonlyexplanation:String; }>,"Classify the bug report and explain the severity in one sentence.",Toolkit<...>,undefined,undefined,undefined>.input: Schema.String
input:
importSchema
Schema.
constString: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<{ readonlyseverity:Literals<readonly ["low","medium","high","critical"]>;readonlyexplanation:String; }>,"Classify the bug report and explain the severity in one sentence.",Toolkit<...>,undefined,undefined,undefined>.output: Schema.Struct<{
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.
@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:
importSchema
Schema.
constString: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<{ readonlyseverity:Literals<readonly ["low","medium","high","critical"]>;readonlyexplanation: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<{ readonlyseverity:Literals<readonly ["low","medium","high","critical"]>;readonlyexplanation:String; }>,"Classify the bug report and explain the severity in one sentence.",Toolkit<...>,undefined,undefined,undefined>.toolkit: Toolkit.Toolkit<{}>
toolkit:
importToolkit
Toolkit.
constempty: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<{ readonlyseverity:Literals<readonly ["low","medium","high","critical"]>;readonlyexplanation:String; }>,"Classify the bug report and explain the severity in one sentence.",Toolkit<...>,undefined,undefined,undefined>.policy?:Partial<Readonly<Omit<{
readonlyrunStatus:"appended"|"off";
readonlymaxTurns:number;
readonlymaxToolCalls:number;
readonlymaxDuration:Duration;
readonlytoolConcurrency:number;
readonlyrepeatedFailureLimit:number;
readonlyonExhaustion:"final-answer"|"fail";
readonlycompletionReserveTokens:number;
readonlytoolResultBounds:ToolResultBounds;
readonlycompaction:CompactionPolicy;
readonlytokenBudget?:number|undefined;
readonlycostBudgetMicrousd?:number|undefined;
readonlycontextTokenLimit?:number|undefined;
readonlyrestartOnJoinedInput?:boolean|undefined;
readonlymodelRetries?:number|undefined;
},"runStatus"| ... 7more... |"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.
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.