An AI agent is a loop in which a model proposes the next action, a program executes it, and the result is fed back. The important boundary is not giving the model broad access; it is expressing tools, argument validation, state, and stop conditions as code contracts.
Core concepts
Break one run into six stages: input, plan, tool call, observation, next action, and completion. The model may propose an action, but the server validates permissions, argument ranges, and idempotency keys. Store state as an event list so a run can be replayed and audited.
Runnable example
from dataclasses import dataclass
@dataclass
class ToolCall:
name: str
args: dict
ALLOWED_TOOLS = {'lookup_ticket'}
def validate(call: ToolCall) -> None:
if call.name not in ALLOWED_TOOLS:
raise ValueError('tool is not allowed')
if set(call.args) != {'ticket_id'}:
raise ValueError('invalid arguments')
if not str(call.args['ticket_id']).startswith('T-'):
raise ValueError('invalid ticket id')
Steps
- Draw the state transition diagram and mark nodes that may run automatically versus nodes requiring human confirmation.
- Define JSON input, return values, timeouts, and error types for every tool, then validate again on the server.
- Set a maximum step count and total duration. Return an explainable paused state at the limit.
- Record the model version, tool name, parameter summary, and result status. Never record tokens or complete customer text.
When to use it
This pattern suits ticket classification, information lookup, and code review. It should not directly replace payment, permission grants, or irreversible production actions.
Common questions
How do I avoid loops? Use step, time, and repeated-action limits together.
Can a model write to a database directly? It should not. Use a restricted service function and an idempotency key.
How should a failure recover? Mark the run as paused, preserve its events, and offer a human handoff.
Official references
OpenAI Agents guide; OpenAI Agents SDK.
Last checked: 2026-11-16. Use the linked official documentation for current versions, interfaces, and safety boundaries.
