Skip to content

Build

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.

action.py
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

StepResponsibility
Register a handlerDescribe the handler and its parameter schema
decideChoose an action and validate its parameters, repairing invalid replies
executeRecheck parameters, guard, pause and disabled actions; invoke the handler
Your handlerAuthorize 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.