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.
from nullprotocol import NullProtocol
def send_message(parameters, context):
print(parameters["text"]) # Replace with your delivery API.
return {"sent": True}
with NullProtocol() as client:
agent = client.load("support")
agent.register_action(
"send_message", send_message,
description="Send a helpful reply to the customer.",
input_schema={
"type": "object",
"properties": {"text": {"type": "string", "minLength": 1}},
"required": ["text"],
"additionalProperties": False,
},
)
decision = agent.decide("The customer says: Good morning!", ["send_message"])
if not decision.success:
raise RuntimeError(decision.error)
execution = agent.execute(decision)
if not execution.success:
raise RuntimeError(execution.error)
print(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.