Decide and execute actions
Let the model prepare a small, typed payload. Keep credentials, business rules and execution in your code.
Register an application handler
This complete example loads an agent and registers a message handler. It prints the prepared message; replace the handler with your application’s delivery function.
import { NullProtocol } from 'nullprotocol';
const agent = await NullProtocol.load({
key: process.env.NULLPROTOCOL_KEY,
agentId: 'support'
});
agent.registerAction('send_message', ({ text }) => {
console.log('Send to customer:', text);
return { delivered: true };
}, {
description: 'Send a helpful reply to the customer.',
input: {
type: 'object',
properties: { text: { type: 'string', minLength: 1 } },
required: ['text'],
additionalProperties: false
}
});
const decision = await agent.decide(
'The customer says: Good morning!',
['send_message']
);
if (!decision.success) throw new Error(decision.error);
const execution = await agent.execute(decision);
if (!execution.success) throw new Error(execution.error);
console.log(execution.result);What each step does
| Step | Responsibility |
|---|---|
| Register a handler | Describe the handler and its parameter schema |
| decide | Choose an action and validate its parameters, repairing invalid replies |
| execute | Recheck parameters, guard, pause and disabled actions; invoke the handler |
| Your handler | Authorize the resource and perform the real API or database operation |
Keep database and API access in the handler
For a catalogue lookup, accept a product query and an optional price ceiling. Your handler translates these fields into a parameterized query or an authenticated API request. Keep tenant filters and authorization in code. Do not execute model-generated SQL directly.
execute returns the handler’s result. It does not automatically send that result back to the model, run another tool or save it to memory. Your application chooses the next step.
Handle execution as a real side effect
Execute the original successful decision on the same SDK agent instance. A decision can be consumed once, including if execution fails. The SDK does not retry a failed handler; use an application-level idempotency key for payments, messages and other external writes.