Agents

Purpose: define runnable Actspan agents by binding prompt behavior, tool declarations, policy, memory, and execution parameters.

Actspan agents are first-class YAML objects. They are not only references to agents built in another framework. A structured agent wraps a reusable prompt; an assistant agent can define instructions directly. Workflows can then call agents, and the CLI, SDK, evals, policies, and portal can reason about them as reviewable runtime targets.

Start Here

For local commands, configure the workspace environment with ACTSPAN_PORTAL_DISABLED=1 in its .actspan.env. Run from that workspace directory and keep the selected provider credentials configured.

An action or prompt defines a provider operation, which may include tool follow-up calls. Add an agent when that behavior needs a stable target name, tool declarations, policy, memory, or eval bindings.

For native execution, start with runtime: { max_steps: 1 }. This selects one outer execution; the provider adapter can still make tool follow-up calls. Increasing max_steps enables the limited outer-execution loop described below.

Run the included agent before changing its declaration:

cd /path/to/actspan-examples/openai/data_enrichment
actspan validate workspace.yaml
actspan run workspace.yaml summarize_agent \
  --input-text "Company: NVIDIA (NVDA). Founded: 1993. Headquarters: Santa Clara, California. Products: GPUs and AI computing platforms. Source: https://www.nvidia.com/en-us/about-nvidia/"

Expected result: Actspan resolves the agent to its prompt, provider, model, and policy and records available execution evidence. A valid runtime declaration does not imply every declared limit is enforced. The direct summary input supplies facts; it does not ask the summarizer to research them.

The syntax below is a declaration reference, not a complete workspace. Start with max_steps: 1; accepted runtime fields do not necessarily enforce limits. Read Runtime Support before depending on them.

Syntax

agents:
  - name: <agent_name>
    agent_type: structured            # or another supported type
    prompt_ref: <prompt_name>
    provider: primary                 # optional; inherits prompt/defaults
    resource: responses
    operation: create
    model: gpt-4.1-mini
    version: 0.0.1                    # optional
    instructions: |                   # optional extra guidance
      ...
    tools: []                         # list replaces defaults.agent.tools
    runtime:
      max_steps: 1

Field notes:

name (required): unique per agent.
agent_type: structured (wraps a prompt) or assistant (instructions-only).
prompt_ref: required for structured agents.
instructions: required for assistant agents.
provider/resource/operation/model: inherit from prompt/defaults for structured agents; required for assistant agents.
version: optional; defaults to 0.0.1 if omitted.
inherit: set false to skip defaults.agent.
tools: can reference registry tools by name, AgentToolRef (name+description), or native Tool objects; replaces defaults.agent.tools.
tool_choice, response_format: same shapes as prompts; optional overrides.
runtime: deep-merged with defaults.agent.runtime; see the support table below before relying on a limit.
memory: mode: in_run applies a recent-turn window, retention, optional summaries, and redaction when conversation state is available. mode: vector, vector_store_id, and namespace are accepted declarations for future support; vector memory is not implemented.
metadata, description, tags: optional annotations.

Runtime Support

Field	Current native behavior
`max_steps`	Bounds outer executions. Set `1` explicitly for the recommended native path; it does not cap all model or tool calls inside an execution.
`max_tool_calls`	Partial support: the multistep loop checks observed calls between outer steps. It does not guarantee a limit before each tool dispatch.
`budget_usd`	Accepted by the schema; not wired into agent execution.
`step_timeout_sec`	Accepted by the schema; not wired into agent execution.
`termination.condition`, `termination.max_idle_steps`	Accepted by the schema; completion and non-progress stopping are not implemented in the outer loop.

With max_steps > 1, each outer step receives the original input plus a generic refinement instruction. Previous step output is recorded in a trace but is not added to the next step's input. The loop stops on its step bound or observed tool count, not on an evaluated final answer.

agent runtime.max_steps
  -> outer execution 1: provider request -> tool result -> provider follow-up
  -> outer execution 2: original input + generic refinement instruction
     (previous outer output is not passed forward)

The OpenAI Responses adapter has a separate function-tool loop with a fixed eight-round bound. It passes tool results back to the provider, but its bound is not derived from agent runtime.max_steps or runtime.max_tool_calls. One outer execution can therefore contain several model and tool calls. Do not use max_tool_calls: 0 as a tool-disable switch; with max_steps > 1, it currently prevents the outer loop from executing any step.

Policy budgets are separate: on supported paths, configured policy can check estimated per-run and daily costs before execution and report actual-cost violations afterward. These checks do not activate runtime.budget_usd or provide an agent-loop cumulative spending bound through that field. See the cost-limit boundary.

Examples

Simple agent:

agents:
  - name: rewrite_agent
    agent_type: structured
    prompt_ref: rewrite_prompt
    runtime: { max_steps: 1 }

Agent overriding model:

agents:
  - name: triage_agent
    agent_type: structured
    prompt_ref: triage_prompt
    model: gpt-4.1
    runtime: { max_steps: 1 }

Assistant agent (no prompt_ref):

agents:
  - name: helper_assistant
    agent_type: assistant
    instructions: "Answer concise Q&A."
    provider: primary
    resource: responses
    operation: create
    model: gpt-4.1-mini
    response_format: { type: json_object }
    runtime: { max_steps: 1 }

Agent with tools and in-run memory:

agents:
  - name: tool_agent
    agent_type: structured
    prompt_ref: tool_prompt
    tools:
      - name: math_tool
        description: "Add two numbers"
      - name: search_tool   # registry tool
    tool_choice: { type: function, name: math_tool }
    response_format: { type: json_object }
    runtime:
      max_steps: 1
    memory:
      mode: in_run
      short_term_window: 5
      retention_turns: 8
      summary_trigger_turns: 6
      redact_sensitive: true
    metadata: { tier: "prod" }
    tags: ["math", "search"]

Validation

actspan validate workspace.yaml
actspan preview workspace.yaml --format json to see agent cost estimates.

Validation checks declaration shape and references. It does not establish enforcement of the declared-only runtime fields above.

Common errors

prompt_ref not found.
Missing provider/model when no defaults/prompt values exist.
agent runtime produced no steps when max_steps > 1 is combined with max_tool_calls: 0.