Actspan Docs Quickstart
DocsGuides

Follow the public research and summary agents and inspect their handoff.

On this page

Run a research and summary workflow

After the quickstart's small prompt, you can run data_enrichment in one command. This guide shows how its research step gathers public company facts and passes them to a summary step for a concise display payload. Use the example supplied with the public Actspan 0.2.0 examples archive.

The workflow supplies web_research output to summarize automatically. You do not need to copy the research JSON between commands.

Before you begin

Install the public CLI and examples and export your OpenAI credential. The quickstart provides a smaller installation check; its optional research section is not a prerequisite. Initialize this extracted workspace separately and keep portal reporting disabled.

From the extracted public examples, open the workspace:

cd "$HOME/actspan/actspan-examples/openai/data_enrichment"
actspan init workspace.yaml --no-env-file --no-portal
export ACTSPAN_PORTAL_DISABLED=1

If you are already in that directory, stay there.

What you will run

Company request
    ↓
web_research → research output
    ↓
summarize → summary output

The researcher uses OpenAI's hosted web-search tool. The summarizer receives the research output through the workflow's input mapping. This example uses neither a managed vector store nor an MCP tunnel.

The supplied workspace.yaml contains both calls, their provider binding, output schemas, two declared agents and their workflow. Each agent selects a prompt and policy; the workflow passes the research output to the summary agent.

Understand the two stages

Step Agent and model Job Output
web_research web_research_agent, gpt-4.1-mini Search for public company information A companies array with name, industry, headquarters, size, website, description and founding year
summarize summarize_agent, gpt-4.1 Summarize the supplied company record schema_version, topic, three to six bullets and a takeaway; optional notes

Both use the primary OpenAI connection. The workspace's exec block selects policies.yaml and the dev policy environment. The calls declare their instructions, models and output schemas; the workflow orders their execution.

The public2 research agent declares runtime.max_steps: 2. These are two named workflow stages, not a guarantee of two provider requests: outer executions, hosted tools, repair and retries can add requests. Previous outer-step output is not fed into the next outer step. See the runtime support table before changing these settings. The published archive remains unchanged.

The research prompt declares its tool with these fields:

tools:
  - type: web_search
tool_choice: required
tool_execution: provider

These fields belong to web_research_prompt. OpenAI hosts the search tool; Actspan sends the configured request and records the response. There is no company database or uploaded document collection in this example.

See how the workflow passes data

This is the execution portion of the existing workflow:

workflows:
  data_enrichment:
    steps:
      - agent:
          id: web_research
          ref: web_research_agent
          input:
            input_text: "${INPUT_TEXT}"
      - agent:
          id: summarize
          ref: summarize_agent
          after: web_research
          input:
            input_text: |
              Topic: ${INPUT_TEXT}
              Research JSON:
              ${web_research.output}
    output:
      from: summarize.output
      format: json
  • agent.ref selects a declared agent; id names this workflow step.
  • after makes summarization wait for research to finish.
  • ${INPUT_TEXT} is the request supplied on the command line.
  • ${web_research.output} inserts the research result into the next input.
  • output.from selects the final result returned by the workflow.

Validate and preview

actspan validate workspace.yaml
actspan preview workspace.yaml

Expected: configuration validation succeeds and preview explains the static execution assessment. Preview makes no provider call and cannot verify model access, provider availability, or the quality of future search results.

Run the workflow

If you already ran the optional research section of the quickstart, reuse that run ID below. Otherwise, or to make a fresh run, use:

ACTSPAN_NO_CACHE=1 actspan run workspace.yaml data_enrichment \
  --input-text "Analyze NVIDIA (NVDA)" \
  --format text

This command makes live model and hosted-tool calls and incurs provider charges. Expected: research runs before summarization, and the command returns a run ID, summary, and recorded usage. A successful run reports execution success, not independent confirmation of the company's facts.

For the request above, the data moves through these stages:

Stage What happens
Load configuration Actspan resolves data_enrichment, its agents, prompts, provider and policy.
Research web_research receives Analyze NVIDIA (NVDA) and requests hosted web search. Its response is checked against the company schema.
Pass context The workflow constructs Topic: Analyze NVIDIA (NVDA) followed by Research JSON: and the research result.
Summarize summarize receives that context and generates the structured summary. It has no search tool of its own.
Return and record The CLI displays summarize.output as readable text and prints a run ID for the recorded execution.

format: json in the workflow defines its output representation. The CLI's --format text displays the result in a readable report. The returned topic should preserve Analyze NVIDIA (NVDA), and the bullets should summarize the company facts. Actual wording and search results vary.

Inspect each stage

actspan runs
actspan inspect "RUN_ID"

Replace <run_id> with the ID printed by this run. Inspect the recorded tools, stage outputs, model, cost, and policy findings before relying on the result.

You should see web_research before summarize. Compare the research record with the summary: did it preserve the facts, and did it add unsupported claims? Schema validation checks the shape of the output; this comparison checks its meaning.

If execution fails, read the failing stage first. Provider authentication or quota errors require fixing the credential/account; a failed output check requires inspecting the output and schema. Retrying does not establish correctness.

Evaluate both behaviors

ACTSPAN_NO_CACHE=1 actspan eval run eval_data_enrichment.yaml \
  --mode smoke --fail-on-constraints

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

Expected: each report names its executed cases, failed checks, and constraint status. Smoke mode is a small first check. Omit --mode smoke when you are ready to execute the full configured suites.

Evaluation What it checks
eval_data_enrichment.yaml Runs web_research_agent and checks that the expected company name appears in its output.
eval_summarize_data_enrichment.yaml Runs summarize_agent with fixed research records; checks topic preservation, schema version, bullet count, takeaway presence, and length.

These test the two calls separately. Neither suite verifies all company facts or replaces checking the output passed between steps in the workflow run above.

The public archive includes these two stage evaluations. Check the workflow trace separately to verify the handoff; neither stage suite alone establishes that every workflow path passed.

Next steps