What people call it. Shown wherever the agent appears.
Agents
One object describes the agent. There is no separate spec and no deploy step.
What an agent is
An agent is one object. There is no separate spec, no manifest and no deploy step: the fields below are the agent, and it is usable the moment you create it.
const agent = await ws.agents.create({
name: 'Refund checker',
instructions: 'You help a support agent decide whether a refund is warranted.',
});Two fields is a real agent
Everything else has a default. Add workflows when it needs procedures, connections when it needs an account, knowledge when it needs to read something. Not before.
Fields
namestringrequired
instructionsstringrequired
Who the agent is, what it is for, and how it should answer. This is the system prompt.
idstringoptionalgenerated
Your own stable id. Unique in your workspace. Omit it and we mint one.
greetingstringoptional
What the agent says before anyone types. Omit it and the agent waits. Costs nothing: no model runs.
grade'standard' | 'premium'optionalstandard
Which class of model the agent thinks with. A premium turn costs five credits, a standard turn one.
filesystem'drive' | 'none'optionaldrive
drive gives every conversation a durable filesystem. none means the agent acts only through its tools, which suits an agent whose whole job is calling them.
workflowsWorkflow[]optional[]
Named procedures. See Workflows.
connectionsConnection[]optional[]
Accounts it needs. See Connections.
secretsSecret[]optional[]
Keys it needs.
parametersParameter[]optional[]
Typed values collected when a conversation starts.
triggersTrigger[]optional[{ kind: 'chat' }]
What starts a run. See Triggers.
toolsstring[]optional[]
Platform capabilities to switch on, such as 'web_search'.
mcpServersMcpServer[]optional[]
MCP servers whose tools it may call. See Tools.
httpToolsHttpTool[]optional[]
Your own endpoints, described so the agent can call them.
Changing an agent
Updating publishes a new version. Fields you leave out keep their current value, so a wording change is one field.
await agent.update({
instructions: '... Be strict about perishable goods.',
});Conversations already running keep the version they started on. New ones get the new version. That is what makes it safe to edit an agent while people are talking to it.
await agent.versions(); // the agent at each version
await agent.get({ version: 3 }); // as it was| Change this | Reaches a conversation already open |
|---|---|
update, setWorkflow, removeWorkflow | No. Each publishes a version |
knowledge.put, knowledge.remove | Yes, on the next turn |
bind, a finished authorize | Yes, for scope: 'fixed' |
setTriggers | Not applicable. A trigger starts a new run |
The rule behind that table
A version pins a reference. Instructions and workflows are the thing, so a version freezes them. Knowledge is a folder and a connection is an account, so the version pins the pointer and what is on the other end stays live. Correcting a policy document reaches a conversation in flight; rewording an instruction does not.
Coming back to an agent
You will not hold the object between requests. Store the id and pick it up again:
const agent = ws.agent(row.agentId); // no network call
const conversation = await agent.start();ws.agent(id) makes no request. You get something you can call methods on, and
the first request happens when you call one.