Providers

Purpose: define where requests are sent and how they are authenticated.

For the complete provider/resource/operation pattern, see the OpenAI provider reference.

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.

Begin from a working workspace and identify its provider alias:

providers:
  primary:
    type: openai
    secrets:
      api_key: ${OPENAI_API_KEY}
    config:
      base_url: https://api.openai.com/v1

Direct OpenAI and Azure OpenAI bindings must declare secrets.api_key even when a portal-managed runtime supplies the value. The reference identifies the source; keep the secret value outside the workspace. A gateway-bound OpenAI provider instead uses its named gateway's secrets.api_key.

Prepare and validate the binding without making a provider call:

actspan setup workspace.yaml
actspan validate workspace.yaml
actspan preview workspace.yaml

Expected result: setup reports the implementation as available, validation accepts its provider-specific fields, and preview identifies the resolved endpoint, model, and credential environment variable without exposing a secret.

Provider implementations are discovered through the versioned actspan.provider_plugins interface. The supplied runtime includes native provider integrations. OpenAI and Anthropic also have independent provider distributions. Explicit external requirements resolve isolated Python packages using package access or a complete wheelhouse supplied for your evaluation.

Dependency Versions

Actspan separates versions that solve different compatibility problems:

actspan.required_version             compatible Actspan CLI/runtime versions
providers.<alias>.plugin_version      compatible independent provider plugin versions
required_providers.<name>.version     advanced provider plugin constraint
providers.<alias>.config.api_version  upstream API version, only when applicable
meta.workspace_version                authored workspace revision

meta.workspace_version: "0.1.0" labels your workspace configuration; it does not select the OpenAI plugin or API version. actspan.required_version checks the installed CLI/runtime version; it does not install Actspan.

Terraform-style provider dependencies use a top-level block:

actspan:
  required_version: ">=0.2.0,<0.3.0"
  required_providers:
    private-model:
      source: acme/private-model
      version: "~> 1.4"
      package: acme-actspan-provider-private-model

providers:
  primary:
    type: private-model

source is the stable provider identity. package is optional when Actspan can infer the distribution name. Artifact delivery uses the operator-configured Python index, including an internal index for restricted networks.

~> 1.4 accepts provider releases from 1.4 up to, but not including, 2.0. actspan init resolves one exact version and records it in .actspan.lock.yaml. actspan init --upgrade intentionally selects the newest compatible version. Normal init reuses the locked artifact.

OpenAI's /v1 URL is not the provider plugin version. The OpenAI plugin owns the supported endpoint families and schemas within that API generation. If an upstream provider introduces a genuinely incompatible /v2, the corresponding provider plugin release adds or selects the new schema/runtime implementation.

For a fresh OpenAI workspace without plugin_version or required_providers.openai, actspan init uses the adapter bundled with the installed Actspan release. A valid existing lock can retain a verified independent adapter. Neither case silently downloads a newer OpenAI adapter; the exact selection is recorded in .actspan.lock.yaml.

The independently packaged OpenAI adapter for this handoff is actspan-provider-openai==0.1.1. To select it when your supplied package index or wheelhouse is configured, add an explicit constraint to the provider binding:

actspan:
  required_version: ">=0.2.0,<0.3.0"

providers:
  primary:
    type: openai
    plugin_version: "==0.1.1"
    secrets:
      api_key: ${OPENAI_API_KEY}

==0.1.1 requires that exact adapter release. Use ~>0.1.1 to accept adapter versions from 0.1.1 up to, but not including, 0.2.0. Both forms require the separate package; the bundled adapter does not satisfy either requirement, even if its version number happens to match. Use actspan.required_providers instead when specifying a custom source or package.

The canonical Anthropic runtime is actspan-provider-anthropic==0.1.0, included as a dependency of core 0.2.0. Bedrock, Azure OpenAI, Vertex AI and Ollama retain their bundled integrations. The tested refund workflow boundaries are described in the Anthropic guide.

Release verification: October 21, 2026

A result qualifies the delivered tuple and behavior in its row, not every registered route. Public CLI results use core 0.2.0 public1, macOS arm64; installation identifies the archive and verification commands. The public examples are 0.2.0/public2. Retain both checksums alongside a run; an installed wheel with the same version label is a separate artifact.

Public immutable archive identities:

• CLI ZIP actspan-0.2.0-public1-macos-arm64.zip, SHA-256 2c88c92cf49ef7d2aedf37cf5397562ea76c1f9530f9ba6d0aafc144286e7f88.
• Examples actspan-examples-0.2.0-public2.tar.gz, SHA-256 ee04ab6b4a45d1849d0c332ef5fc707904ead546897bffa242b3bb7d92385be3.

The supplied-package rows are not anonymous public downloads. Request their qualified handoff manifest for wheel/image hashes and retained run evidence; version numbers alone do not identify immutable artifacts. The guide links explain the scenarios and scope, rather than publishing private raw run data. Do not infer a missing artifact hash from a matching version label.

The framework checks used LangChain 1.4.6, langchain-core 1.6.10, LangGraph 1.2.15, and langchain-openai 1.7.2 or langchain-anthropic 1.7.6. Framework clients own their provider connection; native plugin installation does not supply them.

Historical portal qualification

Authenticated native OpenAI/Claude portal approvals were checked on core 0.1.2, separately from the public 0.2.0 artifact. See the approval evidence and limits. Do not treat this historical browser result as a current 0.2.0 browser test. Published 0.2.0 retains its approval binding exception and direct-prompt receipt-status issue.

Native hosted MCP requires a provider-reachable authenticated endpoint. Local framework MCP and the credential-owning gateway are separate paths; a pass on one does not qualify another. local_test is an offline fixture provider.

Syntax

providers:
  <provider_id>:
    type: <provider_type>          # openai, anthropic, bedrock, azure_openai, ollama, ...
    secrets:
      api_key: ${ENV_VAR_NAME}     # keep keys in env vars
    config:
      base_url: https://...
      region: us

Field notes:

• provider_id: your alias (primary, backup).
• type: adapter name (openai, anthropic, bedrock, ...).
• version: optional provider-owned configuration value; it does not select the provider plugin. Use plugin_version for an official independent adapter or actspan.required_providers for a custom source or package.
• secrets.api_key: required on direct OpenAI and Azure OpenAI bindings; use an environment reference such as ${OPENAI_API_KEY} or ${AZURE_OPENAI_API_KEY}.
• config.base_url: upstream endpoint. config.region: provider-specific setting or admission label; a label alone does not establish processing or retention location. Confirm the endpoint, actual deployment and provider contract.
• config.timeout (seconds, number) for client tuning where supported.

Examples

Single provider (OpenAI):

providers:
  primary:
    type: openai
    secrets: { api_key: ${OPENAI_API_KEY} }
    config: { base_url: https://api.openai.com/v1, region: us }
exec:
  default_provider: primary
  region: us

Two providers with override:

providers:
  primary:
    type: openai
    secrets: { api_key: ${OPENAI_API_KEY} }
    config: { base_url: https://api.openai.com/v1, region: us }
  backup:
    type: openai
    secrets: { api_key: ${OPENAI_API_KEY_BACKUP} }
    config: { base_url: https://api.openai.com/v1, region: us }
exec:
  default_provider: primary

Azure OpenAI:

providers:
  primary:
    type: azure-openai
    secrets:
      api_key: ${AZURE_OPENAI_API_KEY}
    config:
      endpoint: ${AZURE_OPENAI_ENDPOINT}
      api_version: ${AZURE_OPENAI_API_VERSION}
exec:
  default_provider: primary

See Azure OpenAI setup.

The Azure block is a reference pending a live-qualified endpoint, API setting and deployment name. Azure OpenAI registered routes mirror OpenAI-compatible Actspan request contracts for responses, embeddings, images, audio, moderations, files, batches, fine-tuning, vector stores, and realtime. Azure-specific endpoint, deployment/model, API version, secret, and pricing behavior stays under provider: azure-openai.

Anthropic routes include messages/create, tokens/count, models/list|retrieve, message_batches/create|retrieve|list|cancel|results, and files/create|retrieve|list|delete|download. Anthropic schemas are native Anthropic request schemas, not OpenAI aliases.

OpenAI runtime configuration with timeouts:

providers:
  primary:
    type: openai
    secrets:
      api_key: ${OPENAI_API_KEY}
    config:
      base_url: https://api.openai.com/v1
      region: us
      timeout: 30
exec:
  default_provider: primary
  region: us

Amazon Bedrock:

providers:
  primary:
    type: bedrock
    config:
      region: ${AWS_REGION:-us-east-1}
exec:
  default_provider: primary

Bedrock uses AWS SDK credential resolution rather than a custom API key. Common runtime environment keys are AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, and AWS_REGION. See Amazon Bedrock setup.

Registered Bedrock Runtime routes in the built-in adapter include messages/create, messages/stream, models/invoke, models/invoke_stream, models/invoke_bidirectional_stream, tokens/count, guardrails/apply, guardrail_checks/invoke, and async_invokes/create|retrieve|list.

Registered Bedrock Agent Runtime routes in the built-in adapter include agents/invoke, knowledge_bases/retrieve, knowledge_bases/retrieve_and_generate, knowledge_bases/retrieve_and_generate_stream, rerank/invoke, flows/invoke, inline_agents/invoke, sessions/create|get|list|update|end|delete, memory/get|delete, invocations/create|list, and invocation_steps/get|list|put.

Bedrock control-plane support includes typed read-only model, guardrail, inference-profile, and provisioned-throughput discovery routes plus control/invoke for direct boto3 control-plane passthrough.

Ollama local provider:

providers:
  local:
    type: ollama
    config:
      base_url: http://127.0.0.1:11434
      timeout: 120
exec:
  default_provider: local

actions:
  ollama_chat:
    local_answer:
      provider: local
      model: qwen3.5:4b
      stream: false
      think: false
      options: {temperature: 0, num_predict: 400}
      messages:
        - role: user
          content: "${INPUT_TEXT}"

Ollama is the local model runtime; Qwen is the model it serves. No hosted model API key is required. Pull the model before running, and start ollama serve in another terminal if the daemon is not already running:

ollama pull qwen3.5:4b
actspan run workspace.yaml ollama_chat.local_answer --input-text "Summarize this." --no-portal

The native chat adapter supports non-streaming execution with registered Python function tools. It advertises the permitted functions, authorizes each returned call before resolving or importing its callable, and records tool outcomes. max_tool_calls and max_tool_rounds bound the tool loop. It supports tool_execution: provider; streaming chat and hosted web search are not supported. When tools are present, selection requests omit native JSON format; the final tool-free request applies the configured schema. Use explicit native format alongside output_schema and validate_output for both model-side formatting and local output validation.

Complete examples using the same YAML through the CLI and Python SDK:

• Customer service: approved synthetic policy lookup, host-bound synthetic order reads, and a real local SQLite handoff queue. Nine evaluation cases require actual tool evidence. A separate workspace pauses for local review and resumes or rejects the saved draft; a local actor label does not establish authenticated reviewer identity.
• Data enrichment: a bounded Python tool retrieves public Wikipedia introductions for NVIDIA, Microsoft, or Snowflake, then Qwen produces a structured research summary. This lookup requires internet access and is not general or hosted web search.
• Support triage: a smaller separately supplied classification-only example with no tool calls or customer actions; it is not in the public native archive.

Ollama's native admission coverage establishes provider and model allowlists. Mandatory tool-allowlist, input/output-limit, and cost-control coverage remains unsupported; a mandatory requirement without established coverage blocks execution. Named-function dispatch authorization is a separate runtime check, not a claim of universal tool enforcement or an OS sandbox. Legacy policy declarations and mandatory coverage requirements are separate mechanisms. Local API cost fields exclude hardware and electricity costs. Passing the example evaluations does not establish general factual accuracy or parity with every OpenAI capability.

Validation

• actspan validate workspace.yaml
• actspan preview workspace.yaml --format json (never calls providers).
• actspan providers (show installed plugin and route capabilities).

External Provider Plugin

The preferred declaration separates the stable source from the compatible version range:

actspan:
  required_providers:
    private-model:
      source: acme/private-model
      version: ">= 1.4, < 2.0"
      package: actspan-provider-private-model

providers:
  primary:
    type: private-model

actspan init downloads the compatible wheel dependency closure, hashes every wheel, installs the provider into its own cached virtual environment, verifies the manifest and all operation targets, exports and verifies provider schemas, and locks the exact result. It does not install the provider into the active project virtualenv.

Direct URLs, VCS references, local paths, extras, and environment markers are rejected. Set ACTSPAN_PROVIDER_PLUGIN_ALLOWLIST to a comma-separated package allowlist when organization policy requires one.

The earlier per-provider exact pin remains as a compatibility path:

providers:
  primary:
    type: private-model
    plugin: actspan-provider-private-model==1.4.2

Do not combine this legacy field with required_providers for the same provider. --no-install fails when a required plugin is missing; --dry-run reports the installation plan without changing the cache.

Custom provider plugins expose an actspan.provider_plugins Python entry point. Request the plugin-authoring contract and compatibility review from your Actspan contact before connecting a custom package.

Schema Coverage

Actspan pairs registered provider operations with schemas. Registration does not establish live account access, every field combination or workflow qualification. Every registered core provider operation must resolve to a request schema. When a provider uses an identical request contract, the provider schema can reference the canonical schema instead of duplicating it. Azure OpenAI route schemas reference the matching OpenAI route schemas where the request contracts are shared.

Do not add schemas for provider operations that the runtime does not support yet. Add the runtime route and schema together.

Common errors

• Missing env var → “unresolved placeholder ${OPENAI_API_KEY}”.
• Unsupported type → must match shipped adapters.
• Missing required config for a given provider (e.g., Azure resource settings).