Core Concepts

Actspan is an AI agent control plane that connects versioned configuration, policies, evaluations and runtime evidence. Define workloads in YAML, run them, test changes and inspect the configuration and evidence behind the results. The public Actspan 0.2.0/public2 data-enrichment example declares two agents, web_research_agent and summarize_agent, with prompts and a workflow that passes the research result between them.

Start Here

For local commands, configure the workspace environment with ACTSPAN_PORTAL_DISABLED=1 in its .actspan.env and run from that workspace directory.

The quickstart starts with a two-file no-tool hello prompt. For this two-agent example, download the public examples and follow the research workflow. For action governance, start with the governed refund.

Expected result: the two workflow steps produce a structured summary and a local run ID that you can inspect to review the handoff.

Define calls or agents → compose a workflow → execute a run → inspect/evaluate

In this example, summarize_prompt is a reusable prompt selected by summarize_agent. data_enrichment is the workflow definition that coordinates research and summarization. Asking that workflow to analyze NVIDIA creates a run; asking it to analyze Cisco creates another run using the same definitions.

You can also run summarize_agent directly with supplied facts using the optional command in the quickstart. The workflow connects research and summarization when you want both stages.

When you change a model, prompt, or policy, the useful question is which revision ran, which controls applied, and what evidence explains the outcome. A declared permission, an observed tool call, and evidence of enforcement answer different parts of that question. See Why Actspan for the control-plane rationale and current coverage.

The Building Blocks

The released starter declares both agents under agents, bound to web_research_prompt and summarize_prompt. Provider-native response actions are an alternative, not a requirement to rewrite this working example.

A provider alias such as primary is your local name. The provider type selects the implementation; the model identifies what it calls. A valid connection definition does not establish that credentials have quota or model access.

See providers, prompts, and OpenAI response actions for exact fields.

An Agent Is a First-Class Target

A structured agent refers to a reusable prompt. This excerpt shows the relationship already present in the released starter:

agents:
  - name: summarize_agent
    agent_type: structured
    prompt_ref: summarize_prompt
    policy_ref: data_enrichment_openai

The prompt supplies the model, messages, and response schema; the agent binds them to a stable runnable name. Workspace defaults can supply shared settings. The named prompt and policy must exist in that workspace before this snippet can validate. Follow the agent reference when adding those definitions.

An assistant agent can instead define its instructions and provider operation directly, without prompt_ref. See agents for both forms.

A Workflow Coordinates Steps

The released example defines data_enrichment, a workflow that invokes web_research_agent and passes its company facts to summarize_agent.

Company name → research call → company facts → summary call → summary

The web_research step selects the research agent. The summarize step waits for it with after: web_research and inserts ${web_research.output} into the summarizer's input. The workflow returns summarize.output. See the data-enrichment walkthrough for the YAML and what happens when you run it.

Workflow nodes can also branch or pause for user input and approval. A paused workflow has a saved thread; continuing it resumes from its checkpoint. A new run with the same text is a separate execution, not an answer to that pause. See workflows and conversation flows.

Tools, MCP, and Knowledge

Tools give an agent an ability beyond generating text, such as searching or looking up a record. Depending on the supported execution path, a tool may run locally or be hosted by a provider.

Here, the research prompt requests OpenAI's hosted web_search tool to find public company information. The summarizer receives the resulting company record; it does not perform another search. In the optional direct-summary command, the manually supplied facts come from your input instead.

This base example does not use MCP or a vector store. Those are additional ways to connect data in other examples.

MCP is a protocol for exposing tools through a server. A configured MCP endpoint is the connection to that server; the server's implementation determines where its data comes from. An MCP reference alone does not upload documents, create a vector store, or guarantee retrieval succeeded.

Inspect tool-call records and evaluate the answer against the retrieved data. See MCP and tools and managed vector stores.

Policies, Runtime Settings, and Evaluations

Policies express constraints such as permitted models, tool access, and budgets. Runtime settings configure supported agent execution behavior.

runtime.max_steps selects the step budget for the Actspan agent loop; it does not measure a model's internal reasoning steps. Declared tool caps and permissions have execution-path-specific enforcement. Do not infer universal blocking from a field being accepted by validation. Use control verification to inspect supported, unsupported, and unverified checks.

In-run conversation memory and retrieval tools are different capabilities. Vector-backed agent memory is not implemented. Review the runtime support table: agent budget_usd, step_timeout_sec and termination fields are declared-only; tool-count support is partial. Policy admission estimates are separate and do not create an atomic shared spending cap.

The public2 research agent has max_steps: 2. Two named workflow stages do not guarantee two provider requests: outer executions, tool follow-ups, repair and retries can add requests. Previous outer-step output is not passed into the next outer execution.

An evaluation runs dataset cases against an agent, prompt, or workflow and applies the declared checks. Passing proves those checks passed for those cases; it does not prove every future answer is correct. See policies and evaluations.

Setup, Resources, and Execution

apply is resource provisioning, not the command for asking an agent a question. Workspaces with managed dependencies can also prepare or refresh those dependencies during run. The quickstart uses no managed resources.

Local CLI and Optional Portal

Local runs with ACTSPAN_PORTAL_DISABLED=1 in the workspace environment write evidence under .actspan/. They do not require a portal account or local database server. See the local Run Ledger.

The portal adds shared views of agents, evaluations, runs, approvals, releases, and evidence. Connect it when you need those team workflows. Normal configured reporting is best effort; --require-portal makes reporting mandatory for commands that support it. Portal visibility covers recorded execution paths.

Continue with the agent quickstart, then the data-enrichment workflow guide.

Before connecting shared reporting

Connecting the portal changes which records leave your computer and are visible to workspace members. Read product data handling and portal reporting before publishing traces. Local records controlled by the same user are not independently immutable attestations.