Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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

Field
Classic
Tool agent
Description

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

middleware

optional

optional

Agent hooks β€” see Middleware

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

Rule
Detail

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.sendAI for model steps

  • Call ctx.search for RAG retrieval

  • Read/write ctx.state for pipeline data

  • Call ctx.runAgent to delegate (uncommon inside agents β€” usually done in entry)

  • ctx.recordStep for custom observability

Agents do not connect or authenticate themselves. The parent DNotifier must connect() before runWorkflow or runAgent.

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

Language
Guide

JavaScript / TypeScript

Dart / Flutter

Python

Next steps

Last updated