Bound the loop
Set maximum turns, tool calls, time, cost, and output size before a run begins.
AI agents and agentic systems
Design AI agents around authority, state, and measurable outcomes.
An agentic Brain API can choose tools, inspect results, delegate work, and continue across steps. Reliability comes from making every capability, state transition, limit, and approval visible in the product contract.
Architecture overview
Treat the agent as a controlled workflow, not an unrestricted persona.
The model proposes the next step, but trusted application code owns authentication, authorization, tool execution, state, and stop conditions. This separation lets the system remain useful even when a prompt is ambiguous or a model makes a poor choice.
Start with one agent and a small read-only tool set. Add write tools only after the team can trace decisions, validate arguments, prevent duplicate actions, and evaluate the full sequence rather than only the final answer.
ReceiveNormalize the goal, identity, tenant, task type, and risk class.
PrepareAssemble policy, approved context, tools, limits, and route candidates.
DecideAsk the model for a typed next step or final output.
ValidateCheck schema, authorization, policy, freshness, and approval state.
ExecuteRun the tool or return the answer, then record the new state.
StopFinish with an explicit success, blocked, needs-input, or limit status.
Design principles
Make the boundary explicit
These principles keep the implementation understandable as models, data sources, and product requirements change.
Type every tool
Use narrow schemas, side-effect classes, permissions, timeouts, and idempotency rules.
Separate memory
Keep working state, session continuity, and durable records in different policy domains.
Use real handoffs
Delegate only when responsibility, data access, or evaluation criteria genuinely change.
Pause at authority
Return structured action proposals and require approval for consequential operations.
Evaluate the path
Score tool selection, policy compliance, intermediate facts, and final task success.
Recommended reading
Go deeper with field guides
Detailed articles connect the architecture to implementation, testing, operations, and safety controls.
Agentic Brain API Design: Tools, Memory, Handoffs, and Human Approval
How to design an agentic Brain API with bounded tools, explicit state, specialist handoffs, approval gates, and evaluations that reflect real workflow outcomes.
Observability for Agentic Systems: Logs, Traces, Metrics, and Evaluations
A field guide to Brain API observability with correlated logs, traces, metrics, evaluation results, privacy controls, and incident-ready run records.
Secure Prompt and Tool Pipelines: Threat Modeling a Brain API
A practical threat model for prompt injection, tool authorization, data exfiltration, secrets, sandboxing, output handling, and red-team tests in a Brain API.
Questions
Common implementation decisions
Does every agent need multiple models?
No. A single well-evaluated model with a bounded tool set is often simpler and more reliable. Routing becomes useful when tasks have distinct capability, latency, privacy, or cost requirements.
Should agents be allowed to write directly to databases?
Prefer narrow application tools that enforce authorization and business rules. Direct database credentials give the model too much authority and make side effects difficult to review or replay.
When is a multi-agent design justified?
Use specialist agents when roles have different tools, data access, instructions, or success criteria. Deterministic workflow steps are usually better for simple decomposition.
How should an agent ask for approval?
Return a structured proposal with the action, target, arguments, evidence, expected effect, and expiration. Resume only after verifying an authorized approval token.
Next step
Turn the concept into one testable workflow.
Start with a bounded task, versioned request and response schemas, explicit permissions, and a replayable evaluation set.