Agents¶

An agent is the AI that reasons and acts. In Core an agent is a stored definition: a model, instructions, a prompt, skills and tools, under one name and with versions. Your application names the agent and passes the input; the rest is in the definition.

What an agent stores¶

Only the name is required. An agent that stores just a model and an instruction is as valid as one that brings a whole toolset.

This is how an application calls an agent:

{
  "agent": { "id": "support" },
  "input": "My card was charged twice."
}

When to use an agent¶

• You want to change the model, the instructions or the tools without redeploying your application.
• Several applications or channels must use exactly the same assistant.
• You want to measure whether a change is an improvement, with an evaluation.
• Every turn has to keep to a rule, such as never naming a bank account number, with live checks.
• You want to install the same behaviour at several customers, with a publication.
• You hand a key to strangers and want every turn to run as you defined it (the Require an agent setting).

A single one-off request needs no agent: a request can also name the model, the instructions and the tools itself.

Versions¶

Every change is a new version. A version is the whole definition and does not change afterwards. A request uses the latest version, or names a version number to stay on that version after newer ones are made.

An administrator can also save a version as a draft. A draft is a numbered version that only the management console and its API see: you can try it and measure it with an evaluation, and your keys keep using the latest published version until you publish the draft. A key never lists or runs a draft; naming its number answers as if the version did not exist. The same holds for prompts, skills, scripts, workflows, pipelines, evaluations and routing configurations.

A request adds, it does not override¶

A request may add skills and tools to what the agent brings. Setting a field the agent stores to a different value is refused with 400. When you want a different value, you make a new version or another agent. That way you know for every turn which definition ran.

What the agent brings is checked against the policy of the key that calls it. A tool, skill or prompt the key may not reach stays out of reach, even when the agent names it.

How it fits together¶

flowchart LR
    prompt["Prompt<br/>template, pinned to a version"] --> agent
    skills["Skills<br/>instructions for a task"] --> agent
    agent["Agent"] --> model["Model or router"]
    agent --> tools["Tools and toolsets"]
    tools --> knowledge["Search tools over knowledge"]
    agent --> sub["Another agent as a tool"]
    eval["Evaluation"] -.->|"measures"| agent
    checks["Live checks"] -.->|"hold every turn to rules"| agent
    plan["Schedule"] -.->|"calls on a clock"| agent

• Prompts are templates with versions. An agent pins a prompt to one version; the request fills in the variables. A prompt can also be used without an agent.
• Skills are packages of instructions for a task, such as writing release notes. A skill tells the model how to do something; a tool lets the model do something.
• Tools are given to an agent as a single tool, as a toolset or as another agent. Knowledge reaches an agent through a search tool.
• An agent as a tool. An agent can hand work to another agent: the model sees it as one tool and gets the answer as a tool result. An agent running as a tool does not call an agent itself, so agents that name each other in a circle are allowed and the circle ends after one call. Besides that there is the built-in subagent: a nested turn without a definition of its own.
• Evaluations measure an agent: a suite of conversations you write once and replay against a pinned agent version, with rules each answer must meet.
• Live checks hold every real turn of an agent to the same kind of rules while the turn happens: a check can refuse a question, withhold an answer or score a sample of answers afterwards (Live checks).
• Schedules run a request on a clock, for example every working day at six. That request can name an agent.
• Sharing. An agent can go into a publication, together with the prompt, skills and tools it uses.

Read on¶

Tutorial: Build your first agent.

See also Give an agent to a turn as a tool and Make a model call for the fields of a request.