Define an agent
An agent is a named unit of work. Define agents with defineAgent / define_agent, then either register them on a workflow or run a tool agent with standalone runAgent / run_agent.
Classic agent (custom run)
const myAgent = DNotifier.defineAgent({
name: "my-agent", // unique within your app
provider: "open_ai", // optional β default for ctx.sendAI in this agent
model: "gpt-4o", // optional β default for ctx.sendAI in this agent
async run(ctx) {
// ctx.input β workflow or runAgent input
// ctx.state β shared across agents
// ctx.sendAI, ctx.search, ctx.runAgent, ...
return { done: true };
},
});Optional provider / model on the agent are applied automatically to ctx.sendAI unless the call passes its own values.
Tool agent (SDK loop)
Pass tools (from notifier.tools.register or mcp.tools()). You may omit run β the SDK runs the tool agent for you:
const agent = DNotifier.defineAgent({
name: "math-assistant",
instructions: "Use math.add when needed. Be concise.",
provider: "open_ai",
model: "gpt-4o",
observability: true,
tools: [addTool],
permissions: { "math.add": ["execute"] },
});
await notifier.runAgent(agent, { input: "What is 2+2?" });See Tools & MCP agents for full APIs and examples.
Fields
name
required
required
Unique, stable agent id within your app (see note below)
run
required
optional
Custom logic; installed automatically when tools is set
tools
β
required for tool agents
Array from tools.register / MCP
instructions
β
recommended
System guidance for the tool agent
description
optional
optional
Human-readable summary
permissions
β
optional
Tool name β allowed actions
observability
β
optional
Record standalone runAgent runs in the dashboard
provider / model
optional
optional
Defaults for LLM turns
capabilities
optional
optional
Capability flags β each defaults to false
Capabilities
Agents and workflows can declare what they support with these flags: mcpServer, a2a, tools, rag, memory, workflows, humanApproval, and subagents. Any you leave out are false; unknown flags are ignored.
Python uses the same keyword (capabilities={"mcpServer": True}), and Dart uses capabilities: {'mcpServer': true}.
With mcpServer or a2a turned on, a listening agent or workflow can be called from MCP clients such as Claude and Cursor, or from any A2A agent. See Serve agents over MCP and Agent-to-agent (A2A).
Rules
Unique name
Each agent must have a distinct name within your app β a duplicate replaces the earlier agent
Classic run
Async function; return value goes to ctx.runAgent("name")
Tool agents
Each tool must have id and name from the SDK registries
Errors
Throw WorkflowError for expected validation failures
What classic agents can do
Inside run(ctx):
Call
ctx.sendAIfor model stepsCall
ctx.searchfor RAG retrievalRead/write
ctx.statefor pipeline dataCall
ctx.runAgentto delegate (uncommon inside agents β usually done inentry)ctx.recordStepfor custom observability
Registration
Agents are registered on the workflow β not globally:
Host an agent without a workflow
An agent can answer remote calls on its own. Call listen on a connected client that uses WebSocket transport:
Callers send an invoke with agentName: "mermaid-diagram" to this client's userId. The result or error is sent back automatically. Python uses agent.listen(notifier) / agent.stop_listening(), and Dart uses agent.listen(notifier) / agent.stopListening(). Workflows have the same listen / stopListening pair.
The same listening agent also answers MCP and A2A calls when those capabilities are on.
Language guides
Next steps
Last updated