Define agents, steps and tools

An agent definition describes a conversation as steps and transitions. Start with a small flow, then add tools and reusable components as the task grows. Import the builders from @cumulus/sdk/agent; they return serializable objects that Cumulus can validate and publish.

A complete small definition

Save this as cumulus/hello.mjs in a project with the SDK installed. It exports the project and bindings expected by the CLI:

import {
  defineAgent, defineNode, defineEdge, defineProject, defineEnvironment,
} from '@cumulus/sdk/agent';

const welcome = defineNode({
  key: 'welcome', kind: 'conversation',
  instruction: { type: 'static_text', text: 'Hello. How can I help?' },
});
const done = defineNode({
  key: 'done', kind: 'end',
  instruction: { type: 'static_text', text: 'Thanks for calling. Goodbye.' },
});
const agent = defineAgent({
  key: 'hello', name: 'Hello agent', channels: ['phone'], languages: ['en'],
  startNode: welcome, nodes: [welcome, done],
  edges: [defineEdge({
    from: welcome, to: done, slot: 'edges',
    condition: { type: 'prompt', prompt: 'The caller is finished or asks to stop.' },
  })],
});
export const project = defineProject({ key: 'hello_project', agents: [agent] });
export const bindings = defineEnvironment({});

Run ./node_modules/.bin/cumulus validate --project cumulus/hello.mjs. This checks the definition locally. Connecting models, tools and a phone number comes later in the complete tutorial.

startNode identifies the first step. Each edge identifies the step it leaves (from), the next step (to) and when to follow it (condition). The key is the stable identity: changing a display name or moving a file should not change that key.

Choose the step that fits the task

Private keypad nodes have additional requirements described in private workflows. The other native transition slots are skip_response_edge, edge and success_edge; use the slot defined for the node's behavior. An always condition does not make all slots interchangeable.

Write instructions and conditions

Use { type: 'static_text', text } when the agent should say specific text. Use { type: 'prompt', text } when it should respond according to an instruction and the conversation.

Conditions can be unconditional (always), conversational (prompt), equations on variables (equation), or language selection (conversation_language, en/es). A prompt condition asks the model to interpret the conversation. Business authorization still belongs in your backend; a model interpreting a request does not grant permission to perform it.

Use string node keys for loops rather than circular JavaScript objects. A start node and all destinations must exist in the same scope. The compiler rejects duplicate nodes and missing references.

Connect a tool

A tool definition declares an HTTP operation's input, output and execution policy. The handler is separate customer code. In the tutorial, service_guide accepts a delivery/repair topic and returns guidance. A function node references that tool, and responseVariables maps $.guidance into service_guidance for the next conversation step.

Tool input/output schemas determine TypeScript inference and runtime validation. Common strings, numbers, booleans, objects, arrays, enums and unions infer types. More complex valid schemas can infer unknown; validate and narrow those values in your application. Optional, omitted and null are different values.

Choose the response-mapping policy for the result your tool actually returns:

• required: every declared mapping must be present. Use it when a successful lookup always returns the promised fields.
• replace_available: replace the mapped values with those available in this response and clear omitted/null fields. Use it when an authorized lookup can legitimately return fewer fields.

For example, if the first lookup returns name: 'Alex' and the next returns no name, replace_available clears the old name. It does not leave Alex's name attached to the next subject. Map scalar paths, not entire objects or arrays.

See the tutorial's tool contract and customer handlers for matching implementation code.

Reuse a component

defineComponent groups nodes, edges and tools under a scoped key and start node. A component can represent a repeated task such as collecting an address or checking availability. A component node calls that subgraph and follows its return behavior. It remains part of the published graph; it is not another hosted service.

Use a factory to create separate instances under different component keys. Keep each instance's node identities unique within its scope. Tools or components with the same key must have the same definition.

Definition API

AgentDefinition also accepts prompt, startSpeaker, default string variables, declared contextVariables, settings, modelChoice, toolCallStrictMode and native edits. Use typed DraftEdit values for provider, recording, analysis, telephony, knowledge, trigger and layout configuration. Server validation reports unsupported or missing configuration before publication.

Agent, tool, project and integration keys match ^[a-z][a-z0-9_]{0,62}$. Node and component keys allow the native graph identity vocabulary up to 256 characters. Keep definition modules free of application startup code so importing or validating them remains a local operation.