How Actspan works with your code

Keep your business rules in your code. Actspan governs the agent around them.

An AI agent that issues refunds, changes accounts or messages customers needs two kinds of protection. Your application enforces the rules of your business: who owns an account, how much can be refunded, which records exist. Actspan governs the agent: what it is allowed to try, which actions wait for a person, what changed before a release, and the evidence of what actually happened.

This page explains who does what, how the pieces fit together, and walks through one refund from the customer's message to the payment record.

Start here

Read this page before designing your first governed agent. The expected result is a clear split between the controls that belong in your services and the controls Actspan applies to the agent. To see the problem Actspan addresses and its current scope, read Why Actspan. To try it, follow Install Actspan.

Who is responsible for what

Neither side replaces the other. Your service must still refuse a refund above its limit even if an agent asks politely. For calls mediated by its runtime, Actspan checks the approved path and records evidence that you can compare with your service records.

The pieces

The published browser-review proof used a local session on core 0.1.2. Qualify your delivered portal/core tuple, identity provider, reviewer roles and denied-access cases before relying on production approval. See the versioned matrix and product data flow; installing the CLI does not install a portal or the optional LangChain adapter.

One refund, step by step

A customer writes: "My $400 headphones arrived damaged. I uploaded photos. I want $250 back." The refund workflow has an assessment step, a routing step, an approval checkpoint and a payment step.

1. Actspan applies the configured admission checks. On this native path, provider/model, token, temperature and supported estimated-cost checks apply to the admitted request. A violation stops dispatch when admission is block. Follow-up and adapter coverage have their own limits; consult the runtime table.
2. The model assesses the claim. In the assessment step it can see only get_claim, get_order and quote_refund. Payment tools are not advertised to it. A forged request for a tool outside that allowed set is blocked before local dispatch.
3. Your tools use host-supplied identity. In the synthetic trial, get_claim and get_order read REFUND_CUSTOMER_ID, not a customer ID from the model's arguments. This is not a sign-in system; production must supply an authenticated application identity.
4. Your service classifies the refund. quote_refund applies your refund policy and stores a quote for $250 with the authoritative tier approval. The model reports a tier used by workflow routing; it cannot change the service's stored classification. Public2 checks quote/claim/amount receipts but does not bind the reported tier/order to that receipt. The service independently checks the payment; stronger routing-field matching requires the corrected example artifact.
5. Actspan routes the run and pauses it. Because the tier is approval, the workflow stops at the approval checkpoint. No payment tool has run. The paused run shows the reviewer the claim, the amount and the assessment.
6. A person decides. The reviewer approves or rejects. Actspan records who decided, when, the note and the checkpoint's review payload. Locally the reviewer name is a label; in the portal the reviewer is a signed-in user.
7. Only now can the reviewed payment run. The payment step can see only issue_reviewed_refund, and Actspan refuses that tool unless the run has an approved checkpoint.
8. Your service checks the payment again. It pays only if the customer, tier and amount match the stored quote and the refund policy has not changed. Each claim can be paid once, so a retry returns the original payment instead of paying twice.
9. Everything is linked. The run record holds the configuration identity, each policy decision, the approval and the payment tool's inputs. Your ledger holds the payment itself. Together they answer: "Why did the agent refund this customer $250, who allowed it, and under which configuration?"

A $75 refund skips steps 5 to 7 and is paid through issue_auto_refund. A $750 refund is quoted as blocked, and no payment path accepts it.

Before a change reaches customers

The commands below use the native OpenAI refund example in the public examples archive. Complete the refund setup, including provider credentials and REFUND_CUSTOMER_ID=CUST-100, then run them from:

cd /path/to/actspan-examples/openai/refund_agent

eval_refunds.yaml is included there. Before that live evaluation, reset only your selected disposable sandbox ledger with python3 refund_service.py reset; the helper needs host Python 3. Earlier payments on the same claims change the expected outcomes. Keep the provider key configured: evaluation makes live model calls. For the impact comparison, changed/workspace.yaml means a complete candidate copy of the example with an authored edit; preserve its relative tool and policy files. workspace.yaml remains the reviewed baseline.

Failed evaluation constraints return a nonzero exit code, so the same commands can gate a pull request in CI.

The verifier does not execute the full refund scenario. It can return exit 2 with status incomplete because the workflow-execution probe is unsupported, even while supported static admission checks pass. Test automatic payment, pending-before-write, approval, rejection and refusal with the refund guide and independent ledger checks. See verification scope.

When something goes wrong

These cases were observed in the refund example's tests, including a run where the model was misled and the service refused the payment. Inspect nested execution status and same-run receipt errors on the affected public direct-prompt path; see release limitations.

Building it yourself

A single agent with one limit can be governed with a few checks in your own code, and that is a reasonable choice. The work grows with each agent, framework, model and change. Without Actspan you would need to build:

• durable pause and resume for agent runs, with the reviewer's decision bound to the reviewed workflow configuration and guarded continuation
• per-step tool permissions and connected decisions for each integration you choose to govern, with uncovered paths explicitly identified
• supported provider/model, token and estimated-cost checks at the configured admission boundary; inspect declared-only runtime fields separately
• evaluations and impact analysis tied to each configuration change
• one evidence record that links configuration, policy decisions, approvals and tool calls, instead of separate logs

Current limits

• Cooperative boundary. Actspan governs calls that go through its runtime or adapter. Code that calls a model or your service directly is outside it. In a deployment, give the payment credential only to the governed runtime.
• Changes during a pending approval. From 0.2.0, continuation refuses a pending approval when its bound workspace, provider selection, policy or declared tool source changed. Start a new run to review the changed configuration. Public 0.2.0 has a known package-versus-module resolution exception and does not automatically bind imported helpers. Use the documented explicit file entrypoints and keep paused code fixed. The corrected resolver and explicit dependency manifest are source-only until a qualified replacement is delivered. See approvals.
• Tool-code boundary. Approval binding fingerprints declared tool source, but does not attest every transitive helper, dependency or business-data change. Impact analysis and approval binding have different purposes; neither makes arbitrary Python code a sandbox.
• Local reviewers are labels. Signed-in, authorized reviewers require the configured portal path. Historical local browser evidence does not qualify deployed production authentication.
• Provider coverage differs. Native OpenAI and Claude refund workflows have separate tests for automatic payment, resumable approval and blocked payment. LangChain has separate receipt and denial checks; its local risky-action path does not provide the native workflow's resumable approval checkpoint. See the refund guide for the named tested paths.

Use cases

Next steps

Use cases beyond the named refund and support tests are proposed adaptations, not qualified deployments. Trusted Python tools are not sandboxed, and runtime declarations such as budget_usd and step_timeout_sec do not become enforced limits through schema validation.

Start with the free CLI and one workflow: install Actspan, then verify its controls. For shared approvals with signed-in reviewers and team evidence, join the design-partner program at info@actspan.com.