Libraries

agents

This library is the standard turn of an agent.

An agent makes each turn with a script, which by default calls this library's turn. A definition replaces that script with turn: ./my-turn.js, and the replacement may call the library.

require("agents").turn(input)makes one turn; gives { turn, text, calls, stop, usage } require("agents").conversation(input)returns the conversation so far, a list of parts require("agents").attach(parts, input)returns the parts, with each image or PDF the model was shown added as files, when its service accepts it

turn calls conversation, then attach, then llm.chat with the model in input. A script that changes what the model is sent makes those calls itself. llm gives the parts of a conversation.

A turn's input has these fields.

model{ name, service, address, key, effort, reply, own }; key is a secret's name systemthe system prompt tools[{ name, does, args }] turnsthe blobs that hold the conversation so far addthe parts that this turn adds to the conversation blobsthe blobs the model has been shown, by the names it knows them by shapethe shape of the agent's result, from output:

A turn returns these fields.

turna blob, made with blobs.make, of this turn's parts as JSON: input.add, then the reply; without it the agent fails textthe model's reply callsthe tool calls the model made: [{ id, name, args }]; when there are none, text is the agent's reply stop"end", "tools" or "length"; on "length" the agent tells the model that its reply was cut short and takes another turn usage{ input, output }, in tokens

This turn calls no model and answers at once.

# quiet.yaml

agent: quiet
model: { name: sonnet, service: claude-code }
prompt: Is there anything to do?
turn: ./quiet.js

// quiet.js

const reply = { role: "assistant", content: "Nothing to do.", calls: [] }
return {
  turn: blobs.make((input.add || []).concat([reply]), { type: "application/json" }),
  text: reply.content, calls: [], stop: "end", usage: { input: 0, output: 0 },
}

corbie test quiet.yaml

This turn calls the library's turn and logs each reply.

# heard.yaml

agent: heard
model: { name: claude-sonnet-5-5, secret: ANTHROPIC_KEY }
prompt: Say hello.
turn: ./heard.js

// heard.js

const reply = require("agents").turn(input)
log("the model said", reply.text)
return reply

corbie test heard.yaml --secret-env ANTHROPIC_KEY