The four operations
Choose the operation for each request. You can use all four on the same agent.
Load your agent once
from nullprotocol import NullProtocol
client = NullProtocol()
agent = client.load("order-reader")The examples on this page use the loaded agent. Keep the client open while running them, then call client.close(). In your app, use with NullProtocol() as client to release its connection pool automatically. Each operation receives its saved instructions and included context.
Extract structured fields
Use extract(data, schema) when the application needs data in a specific shape. Shorthand fields are required; use JSON Schema for enums, nullable fields and more detailed constraints.
result = agent.extract(
"Order 42: two blue mugs.",
{"orderId": "number", "quantity": "number", "item": "string"},
)
if not result.success:
raise RuntimeError(result.error)
print(result.data)Summarize supplied text
result = agent.summarize(
"The parcel arrived late. One mug was cracked. The buyer wants a replacement.",
max_length=300, focus="problem and requested resolution",
)
if not result.success:
raise RuntimeError(result.error)
print(result.summary, result.key_points)max_length limits the summary in UTF-16 characters. The SDK default is 200; HTTP and Try agent default to 1000. Set it explicitly when comparing results across integrations.
Check a claim against rules
result = agent.validate(
"Every claim must agree with the supplied policy.",
"Gift cards are refundable.",
reference="Gift cards are not refundable.",
)
if not result.success:
raise RuntimeError(result.error)
print(result.recommendation, result.score, result.reasoning)A successful operation returns a recommendation: pass, fail or conditional. A true success means a checked reply was returned; it does not mean the claim passed. The score is the model’s judgement, not a calibrated probability.
Choose the next action
result = agent.decide(
"The customer reports damage but has not supplied a photo.",
[
{"action": "request_photo", "description": "Ask for a photo of the damage."},
{"action": "human_review", "description": "Ask a person to review the request."},
],
)
if not result.success:
raise RuntimeError(result.error)
print(result.action, result.parameters, result.reasoning)decide returns a choice and a payload. It does not send a message, query a database or run an external API. Use a registered application action when you want the SDK to validate parameters and execute a handler.
Check the result before using it
Operations return a false success with error_code and error when they fail or are refused. Invalid model replies get the server’s normal repair attempt. A failure can still consume tokens. Loading an agent can raise an exception, so handle setup failures in your application as well.