Run Your First Agent

Run a small OpenAI prompt using two files you create below. No private repository or supplied examples are needed. Then, after downloading the public examples, continue with the research-and-summary workflow later on this page.

Start Here

Install the Actspan 0.2.0 CLI first. The small example below uses the bundled OpenAI provider, with no separate plugin, host Python, web search, tools, or portal required.

Initialization, validation and preview make no model calls. You can check the configuration with a dummy key before using your own OpenAI account for a live request. Expected result: one runnable prompt named hello, a selected policy, and a static preview with no schema errors or admission block.

Create a Small Workspace

Create a new directory, separate from your other Actspan workspaces:

mkdir actspan-hello
cd actspan-hello

Save this as workspace.yaml:

actspan:
  required_version: ">=0.2.0,<0.3"
providers:
  primary:
    type: openai
    secrets:
      api_key: ${OPENAI_API_KEY}
exec:
  default_provider: primary
  region: us
  policy_file: ./policies.yaml
  policy_env: dev
prompts:
  - name: hello
    version: "0.1.0"
    provider: primary
    resource: responses
    operation: create
    model: gpt-4.1-mini
    max_output_tokens: 128
    temperature: 0
    input:
      - role: user
        content:
          - type: input_text
            text: ${INPUT_TEXT}

Save this as policies.yaml in the same directory:

policies:
  - name: hello_policy
    version: "0.1.0"
    provider: openai
    resource: responses
    operation: create
    admission:
      mode: block
    allow:
      providers: [openai]
      models:
        openai: [gpt-4.1-mini]
    limits:
      max_output_tokens: 128
      max_temperature: 0

The policy allows this OpenAI model and caps requested output at 128 tokens with zero temperature. It uses blocking admission. There is one policy entry, so Actspan selects it by its provider, resource and operation. The prompt and policy versions are configuration versions, separate from the CLI release version.

Check it without a model call

For these offline commands, the placeholder is deliberately not a working key:

export OPENAI_API_KEY="<public-docs-offline-placeholder>"
export ACTSPAN_PORTAL_DISABLED=1
actspan init workspace.yaml
actspan validate workspace.yaml --strict-env
actspan preview workspace.yaml \
  --input-text "Say hello in one sentence." \
  --strict-env --strict-schema --admission block --format json

Expected: initialization finds the built-in OpenAI provider with nothing to install; validation succeeds; preview includes the hello prompt, policy hello_policy version 0.1.0, policy environment dev, no schema errors and admission_any_block: false. Init creates local metadata, a pricing table and a credential-free .actspan.env; your two authored YAML files remain the source. The placeholder satisfies configuration checks only. These commands do not verify provider authentication, model access, quota or future output quality.

Make a live request when you are ready

Replace the dummy key in your shell with a real OpenAI API key:

export OPENAI_API_KEY="<your-real-openai-api-key>"
actspan run workspace.yaml hello \
  --input-text "Say hello in one sentence." \
  --format text

This command sends the prompt to OpenAI and incurs provider charges. Keep the key out of YAML and source control. On success, expect a short response and a local run ID. Inspect the actual ID printed by the CLI:

actspan runs
actspan inspect "RUN_ID"

This first example makes one plain model request. For tool execution and human review, continue with the refund-agent guide.

Public Research Workflow

The remaining walkthrough uses the versioned public examples archive. It is an optional deeper path after the two-file example; it is not required to try the CLI.

Start with a company request. The supplied data-enrichment workflow runs a research call, passes its structured output to a summary call, and records the execution locally. You can inspect the result and evaluate the summary stage.

Company request → web_research → summarize → structured summary

This example uses OpenAI hosted web search. It needs no MCP server, vector store, or portal.

Use the CLI and matching public examples for Actspan 0.2.0. Follow download the public examples to get the files. You also need an OpenAI API key with access to the example's models and hosted web search.

Expected result: a structured summary, a local run ID and an evaluation report. The run and evaluation make live provider calls and incur provider charges. Initialization, validation and preview make no model calls.

1. Open the Supplied Example

From the extracted examples directory:

cd "$HOME/actspan/actspan-examples/openai/data_enrichment"
actspan --version

Expected: the version contains 0.2.0. Use the examples supplied with that version; no private repository clone is needed. The example already contains its provider binding, prompts, policy, workflow and evaluations.

2. Configure Credentials and Local Mode Once

actspan init workspace.yaml

Initialization discovers the provider, prepares local metadata, and creates .actspan.env if it does not already exist. A new local file contains the portal setting only. Existing files and explicit portal settings are preserved. Init does not test API credentials.

The generated .actspan.env contains:

ACTSPAN_PORTAL_DISABLED=1

Export your key in the current shell before a live run:

export OPENAI_API_KEY="<your-openai-api-key>"

The key is not written to .actspan.env or YAML. The export applies to this shell session; export it again in a new shell. Init preserves existing enabled portal settings. Commands run from this directory use local evidence without a portal flag. Provider requests still go to OpenAI.

When shared reporting is needed, follow enable portal reporting later.

3. Validate the Workspace

actspan validate workspace.yaml

Expected: validation reports the workspace is OK. This checks configuration, references, and policy compatibility without calling OpenAI. A passing result does not establish that your key has model access or quota.

Preview the static execution plan before the live run:

actspan preview workspace.yaml --format json

Preview makes no model or hosted-search calls. It shows the plan and available estimates; provider access and quota are checked only by a live check or execution.

The runnable target is the data_enrichment workflow. Its web_research step calls the declared web_research_agent, then summarize calls summarize_agent with the research result. Their prompt references are web_research_prompt and summarize_prompt. The workflow guide shows the existing input mapping.

4. Run Research, Then Summarize

Supply a real company name. The workflow passes the research JSON between its steps, so the command needs only the company request:

actspan run workspace.yaml data_enrichment \
  --input-text "NVIDIA Corporation" \
  --format text

The research call uses OpenAI hosted web search and returns structured company facts. The workflow then supplies those facts to the summarizer automatically. The summarizer's response schema requires JSON output; --format text controls how the CLI prints it. A successful run does not independently verify every fact returned by the provider.

On success, the CLI prints a run ID and a summary containing:

• schema_version: 1
• topic: NVIDIA Corporation
• bullets: three to six summary points
• takeaway: a short conclusion

Wording, latency, token use, and cost can vary. These are expected output fields, not a promise that every provider call succeeds.

Run the summarizer on its own

The workflow command above already runs the summary call. To call it separately, provide the facts yourself. This makes another model call and does not reuse the research output from the workflow run:

actspan run workspace.yaml summarize_agent \
  --input-text 'Topic: NVIDIA Corporation
Research JSON:
{"companies":[{"company_name":"NVIDIA Corporation","industry":"Semiconductors","headquarters_location":"Santa Clara, California, United States","company_size":"30000+","website":"https://www.nvidia.com","description":"NVIDIA builds GPUs and accelerated computing systems.","founded_year":1993}]}' \
  --format text

5. Inspect What Happened

Copy the run ID printed by the workflow command. If you ran the summarizer on its own, use that command's run ID to inspect its separate run:

actspan runs
actspan inspect "RUN_ID"

Replace <RUN_ID> with the actual ID. Inspect the recorded status, research and summary steps, selected providers and models, output, and usage. Local run records live under .actspan/; no portal is needed.

6. Evaluate the Agent

Run the included summarize evaluation with a small smoke dataset:

actspan eval run eval_summarize_data_enrichment.yaml \
  --mode smoke \
  --fail-on-constraints

This evaluates the summary stage with fixed company records; it does not repeat web research. It makes additional model calls and checks the topic, schema version, bullet count, takeaway, and length. Look for constraints_ok: true; the output also gives report and case-record paths.

An execution error or failed configured constraint produces a nonzero exit code. Inspect failed cases and must-pass counts even when constraints pass. Read the failed-case details before changing the prompt. Remove --mode smoke to test the full dataset.

If a Step Fails

Next: Understand the Agent Handoff

The data-enrichment workflow guide explains how the research output becomes the summarizer's input and how to inspect each stage. Read core concepts and open the supplied workspace.yaml in your editor to review the configuration behind the run.