Actspan Docs Quickstart
DocsReference

Call the configured runtime from application code.

On this page

Python SDK Guide

Purpose: help Python application teams embed Actspan runtime behavior in backend services while keeping prompts, agents, workflows, and governance in YAML.

Before you begin

The SDK needs the separately supplied Python distribution installed in your application's virtual environment. The self-contained public CLI does not install an importable actspan package into host Python. Design partners receive core and provider wheels, a dependency lock/wheelhouse and a compatible Python version through their handoff. Do not substitute the native executable for it. Use that exact tuple; provider plugins have independent versions. Before a live request, check the prepared interpreter without contacting a provider:

"$ACTSPAN_PYTHON" -c 'from importlib.metadata import version; from actspan.sdk import ActspanClient; print(version("actspan"))'

Set ACTSPAN_PYTHON to the handoff's absolute virtual-environment interpreter. For example, isolated Anthropic and LangChain have additional requirements in their provider and framework guides. A successful import does not qualify model access, tools or approval continuation.

Start Here

Before adding SDK code:

  1. install Actspan in the application environment
  2. run and validate the target workspace through the CLI
  3. export the selected provider credential

Then execute the same YAML-defined workflow in process:

from actspan.sdk import ActspanClient

client = ActspanClient(
    workspace="workspace.yaml",
    track=False,
)

result = client.run_workflow(
    "data_enrichment",
    "Analyze NVIDIA (NVDA)",
)

print(result.status)
print(result.run_id)
print(result.final_output)
print(result.usage)

Expected result: result.ok is true and the typed result contains a run ID, final output, and usage evidence. Tracking remains local because track=False.

When To Use The SDK

Use the SDK when:

  • your service is written in Python
  • you want application code to stay thin
  • YAML should remain the behavior definition surface
  • Actspan should own the prompt, agent, tool, and workflow definitions
  • policies and evals should stay outside request-handler logic

Typical entrypoints:

  • ActspanClient(...)
  • run_prompt(...)
  • run_agent(...)
  • run_workflow(...)
  • ActspanRuntime(...)

What The SDK Does

  • executes YAML-defined prompts, agents, and workflows in-process
  • reuses the same core runtime as the CLI
  • returns typed results and typed exceptions
  • optionally emits cloud tracking events

It does not:

  • subprocess the CLI
  • require agent orchestration to be rebuilt as application code
  • move prompt or workflow logic into application code

Continue Learning

  1. Review execution status.
  2. Read product data handling before connecting reporting.
  3. Validate the YAML workspace in CI before loading it in a service process.

Typical Backend Flow

1. Keep YAML In The Repo

Application code should point to a workspace path and target name, not rebuild prompts or workflow graphs inline.

2. Call The Runtime

Create an ActspanClient when the same workspace, service metadata, and tracking defaults are reused across many calls. Use run_prompt, run_agent, or run_workflow directly for one-off scripts and lower-level integrations.

Workflow calls execute normally with the workspace's policy and runtime controls. Select a block-mode policy when admission must reject disallowed calls. No profile or baseline-recording option is needed. Evaluate and inspect the resulting evidence; compare two saved run IDs explicitly when reviewing a change. For optional automatic comparison after a live run, set execution.profile: managed_live in the workspace. It warns by default and still makes normal provider and tool calls. The lower-level runtime supports admission options that are not arguments on ActspanClient.run_workflow; configure effective block-mode policy for the client example above. Use the supplied SDK reference for your exact package.

3. Handle Typed Failures

Catch:

  • ActspanRuntimeError
  • ActspanValidationError
  • ActspanPolicyError
  • ActspanExecutionError

The following handler uses the existing RuntimeResult and ActspanRuntimeError contract. It is an application integration pattern, not a new live provider qualification:

from actspan.sdk.runtime import ActspanRuntimeError

try:
    result = client.run_workflow("data_enrichment", "Analyze NVIDIA")
except ActspanRuntimeError as exc:
    print("Execution failed:", exc.error_code, exc.status)
    # Inspect receipts before retrying an operation that could have written.
else:
    if result.status in {"waiting_for_user", "pending_approval", "pending_handoff"}:
        print("Paused:", result.status, result.thread_id)
    elif result.status in {"failed", "error"}:
        print("Execution failed:", result.status)
    elif result.status in {"success", "succeeded"}:
        print("Completed:", result.final_output)
        # Accept the application's expected business outcome separately.
    else:
        print("Inspect unexpected state:", result.status)

result.ok excludes error/failed status; it does not mean every pending state is a completed business success. A completed blocked business outcome can be valid. Public 0.2.0's known direct-prompt outer-status limitation is documented in release notes; a source-only correction must not be assumed present in another distribution labeled 0.2.0.

4. Keep Tracking Optional

Enable track=True or provide a RuntimeTrackingConfig(...) only when you want cloud run visibility.

For a service that must record shared evidence, use an explicit workspace service token and required portal configuration:

from actspan.sdk import ActspanClient, PortalConfig

portal = PortalConfig.from_env(required=True)
client = ActspanClient(
    workspace="workspace.yaml",
    portal=portal,
)

result = client.run_workflow("data_enrichment", "Analyze NVIDIA")

Required environment variables:

ACTSPAN_CLOUD_API_BASE_URL
ACTSPAN_CLOUD_AUTH_TOKEN
ACTSPAN_CLOUD_WORKSPACE_ID
ACTSPAN_CLOUD_DEFAULT_ORG_SLUG

Passing PortalConfig enables tracking by default. required=True fails the SDK operation when the portal cannot accept evidence. Explicit track=False disables portal communication for that call. Required reporting is not a transaction around a business write: local execution may commit a tool action before a later upload fails. Inspect the service record before retrying; retry eligible evidence delivery rather than blindly repeating the action. See portal reporting.

Application Integration Contract

Application teams should call the SDK from request handlers, jobs, or service methods while keeping prompts, agents, workflows, provider config, policies, and eval references in YAML. The SDK integration path is runtime-first; evals remain an operational quality workflow run through CLI/CI and reviewed in the portal.