Defaults block

Purpose: reduce repetition by inheriting provider/model/runtime settings.

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.

Add defaults only after one prompt or agent works with explicit fields. Move one repeated provider or model setting into defaults, then verify the effective configuration did not change unexpectedly:

actspan validate workspace.yaml
actspan preview workspace.yaml

Expected result: preview shows the same resolved provider, model, and runtime settings for every target that inherits the new default.

Syntax

defaults:
  prompt:
    provider: primary
    resource: responses
    operation: create
    model: gpt-4.1-mini
    query:
      stream: false
  agent:
    tools: []
    runtime:
      max_steps: 1

Field notes:

• prompt.provider, prompt.resource, prompt.operation, prompt.model: applied to every prompt unless the prompt overrides.
• prompt.query: object of request params (e.g., stream, temperature, max_output_tokens, etc.); merged shallowly, and prompt-level values win.
• agent.tools: list override; an agent’s own tools list replaces the default list.
• agent.runtime: deep-merged; agent runtime keys (adapter-specific) win over defaults.

Example

defaults:
  prompt:
    provider: primary
    resource: responses
    operation: create
    model: gpt-4.1-mini
    query: { stream: false }
  agent:
    tools: []
    runtime: { max_steps: 1 }

Validation

• actspan validate workspace.yaml
• actspan render <workspace_dir> writes .actspan/effective.yaml with defaults and inferred prompt route fields materialized.
• actspan render <workspace_dir> --resolved prints the fully resolved workspace (env-expanded + defaults applied).

max_tool_calls has partial runtime support. A zero value is not a tool-disable switch and can prevent all outer steps when max_steps > 1. Use supported tool permissions to restrict tools instead.

Treat render --resolved output as sensitive: it expands environment values and is not a guaranteed redacted support artifact. Review it locally and remove credentials before sharing. Prefer validate and preview for routine configuration checks; review their output for application data as well.