Skip to main content

Agent

1. Definition​

An Agent is a goal-oriented AI capability that can determine a sequence of actions, select permitted tools, execute them, observe results, and continue until it reaches a completion or control condition.

flowchart TD
    G(["Goal"]):::actor --> P["Reason / Plan"]:::model
    P --> S["Select permitted tool or action"]:::govern
    S --> E["Execute"]:::process
    E --> O["Observe result"]:::process
    O --> D{"Control condition"}:::gate
    D -->|"Goal met"| C(["Complete"]):::output
    D ==>|"More work"| P
    D -->|"Approval required"| A["Request approval"]:::govern
    D -->|"Failure / policy boundary"| F(["Fail or escalate"]):::govern

    classDef actor fill:#DBEAFE,stroke:#1D4ED8,stroke-width:1px,color:#0B1220
    classDef process fill:#EEF2F7,stroke:#475569,stroke-width:1px,color:#0B1220
    classDef model fill:#EDE9FE,stroke:#6D28D9,stroke-width:1px,color:#0B1220
    classDef gate fill:#FEF3C7,stroke:#B45309,stroke-width:1px,color:#0B1220
    classDef govern fill:#FFE4E6,stroke:#BE123C,stroke-width:1px,color:#0B1220
    classDef output fill:#DCFCE7,stroke:#15803D,stroke-width:1px,color:#0B1220

2. Agent Runtime Responsibilities​

A mature Agent runtime may manage:

  • Model calls.
  • Instructions.
  • Tool definitions.
  • Tool selection.
  • Agent loop/turns.
  • Structured outputs.
  • Handoffs or sub-agents.
  • Session state.
  • Guardrails.
  • Human approval.
  • Trace/observability.
  • Maximum steps and termination.

Official agent SDKs differ in implementation; the Site should normalize them behind a common execution contract.

3. Client SDK vs Agent SDK​

Model/client SDKs and agent SDKs serve different runtime responsibilities:

Model/Client SDKAgent SDK
Calls model/provider APIsManages an agentic execution loop
Application owns orchestrationRuntime may own turns/tool dispatch
Application owns most stateSessions/state mechanisms may be included
Best for bounded model callsBest for multistep tool use
No agent semantics requiredInstructions, tools, guardrails, handoffs common

For example, OpenAI's current guidance differentiates direct Responses API use from the Agents SDK based on who owns the loop, tool dispatch, state, guardrails, and handoffs.

4. Sandbox and Isolation Policy​

A sandbox is not universally required for every agent.

Use a sandbox or isolated workspace when the agent must:

  • Execute code.
  • Modify files or repositories.
  • Use shell tools.
  • Operate on untrusted artifacts.
  • Use browser/computer automation.
  • Maintain an isolated workspace across steps.

A conversational agent calling safe server-side APIs does not require a sandbox solely because it is an agent.

5. Agent Configuration​

capability_type: agent
runtime:
  type: agent_sdk
  implementation: provider-or-custom
model_ref: model-reference
prompt_template_ref: agent-instructions-v1
knowledge_refs:
  - engineering-knowledge
allowed_tools:
  - search-business-object
  - create-task
  - notify-owner
controls:
  max_steps: 12
  timeout_seconds: 300
  require_approval_for:
    - write_external_system
    - delete
    - financial_commitment

6. Tool Policy​

Tools should be registered with explicit metadata:

  • Name and description.
  • Input schema.
  • Output schema.
  • Authentication method.
  • Permission requirements.
  • Side-effect classification.
  • Approval requirement.
  • Idempotency behavior.
  • Timeout and retry policy.
  • Audit category.

7. Example​

Goal: "Review current application vulnerabilities, identify critical items, create remediation tasks, and notify the responsible owners."

flowchart TD
    AG[["Agent"]]:::model --> V["Fetch vulnerability findings"]:::process
    V --> R["Identify critical findings"]:::model
    R --> O["Retrieve owner mapping"]:::store
    O --> T["Create remediation task"]:::process
    T --> N[["Invoke notification automation"]]:::process
    N --> X["Verify task result"]:::process
    X --> S(["Return summary"]):::output

    classDef process fill:#EEF2F7,stroke:#475569,stroke-width:1px,color:#0B1220
    classDef model fill:#EDE9FE,stroke:#6D28D9,stroke-width:1px,color:#0B1220
    classDef store fill:#CCFBF1,stroke:#0F766E,stroke-width:1px,color:#0B1220
    classDef output fill:#DCFCE7,stroke:#15803D,stroke-width:1px,color:#0B1220

This is an Agent because the required steps may depend on the observed findings rather than a completely predefined sequence.

8. Agent vs Automation​

If every step and branch is known before execution, implement the process as Automation and optionally call a model inside the workflow.

Use Agent logic only where dynamic reasoning or tool selection provides real value.