Agentspan is an open-source execution layer for AI agents whose work must survive process crashes, deployments, long waits and human approvals. Instead of keeping the entire agent loop in application memory, it stores execution state on an Agentspan server and delegates tool work to connected workers. The project is built by Orkes on the Conductor workflow engine and is currently MIT licensed and self-hostable.
The distinction matters: Agentspan does not make a weak agent intelligent, choose safe permissions or validate a business result. It changes the failure model. A run gets a durable identity, completed steps have history, pending approval can wait server-side, and a replacement worker can reconnect. Teams should evaluate it as distributed-systems infrastructure, not as a prompt library.
What changes when state moves out of the agent process
| Concern | In-process agent loop | Agentspan model | Operator still owns |
|---|---|---|---|
| Process crash | Memory and current position may disappear | Server retains workflow state and resumes work | Worker availability and idempotent tools |
| Human approval | Application must keep or rebuild pending state | Workflow can pause server-side and receive a response later | Approver identity, timeout and escalation policy |
| Retries | Custom loop, often coarse-grained | Per-step retry is a workflow primitive | Which errors are retryable and whether side effects are safe |
| History | Application-specific logs | Inputs, outputs, timing and steps are queryable | Redaction, retention and access controls |
| Scale | State and scheduling coupled to one process | Server coordinates workers and executions | Capacity, tenancy, queues and disaster recovery |
| Scheduling/events | Separate cron or message plumbing | Conductor scheduling and event integrations | Overlap, deduplication and missed-event behavior |
The runtime path, drawn as a failure boundary
user / event
|
v
.--------------------. durable state .----------------------.
| application code | ------------------------> | Agentspan / Conductor|
| Agent + tools | <--- task delegation ---- | run, step, history |
'--------------------' '----------+-----------'
| worker may die |
| and reconnect | calls
v v
custom tool process LLM / HTTP / MCP tools
| |
'---------------- results + side effects ---------------'
Durable checkpoint ≠ transaction over every external side effect
The last line is the most important operational caveat. A workflow engine can remember that it requested a payment, email or repository mutation, yet it cannot automatically make an arbitrary external action transactional. If a worker succeeds remotely and crashes before acknowledging completion, a retry may repeat the action. Every mutating tool needs an idempotency key, reconciliation query or human decision path.
Do the crash test before the happy-path demo
A useful proof of concept deliberately kills the worker at different boundaries. Run one read-only research job, one job with a controlled side effect, and one approval-gated job. Preserve the execution ID, restart on a different machine, reconnect, and compare the final state with an uninterrupted control run.
| Injection point | Expected evidence | Failure that should block rollout |
|---|---|---|
| During an LLM request | Bounded retry and one coherent continuation | Unbounded token spend or duplicated context |
| After read-only tool completion | Resume without losing prior result | Run restarts from the beginning |
| After remote write, before acknowledgement | Idempotency key prevents a duplicate | Two tickets, payments, messages or commits |
| While waiting for approval | Restart preserves pending request and audit identity | Implicit approval, lost request or wrong approver |
| During deployment | Old and new workers do not execute the same exclusive step | Split-brain side effects |
| After server restart | Documented recovery objective is met | History or workflow state is unrecoverable |
Retries need a side-effect contract
Classify tools before enabling automatic retries. Pure functions and repeatable reads can usually retry. Writes require a stable operation key scoped to the workflow and step. Non-repeatable actions need a “query before retry” adapter or a manual reconciliation queue. Do not ask an LLM to infer whether a payment or message already happened from conversational context.
- Safe retry: calculate a checksum, read a public page or query by immutable ID.
- Conditionally safe: create a ticket with a server-enforced idempotency key, or update a known record with version checking.
- Unsafe by default: send an email, publish content, transfer money or execute a production change without deduplication.
- Compensatable: reserve a resource when a tested cancellation operation and accountable escalation path exist.
Human approval is a policy system, not a pause button
Agentspan documents tools marked for approval and CLI, API or UI responses. Production policy must additionally define who can approve, what exact arguments are frozen, how identity is authenticated, when the request expires and whether a modified action creates a new approval. Show the approver the proposed side effect, destination, data disclosure, estimated cost and a human-readable diff.
Separate requesters from approvers for high-impact actions. Denial must terminate or narrow the action; it should not prompt the model to route around the gate with another tool. Record the policy version and approval artifact alongside the run so a replay cannot apply an old decision to new arguments.
Framework compatibility does not mean identical semantics
The official documentation demonstrates its own Agent API and integrations with LangGraph, the OpenAI Agents SDK and Google ADK. Test the exact adapter and version you plan to deploy. Check streaming, cancellation, nested agents, tool-call IDs, structured output, context propagation and error mapping. A wrapper can preserve the callable interface while changing checkpoint or retry behavior.
| Integration choice | Best reason to use it | Validation question |
|---|---|---|
| Native Agentspan Agent | Smallest conceptual surface and documented primitives | Does its model/tool abstraction cover required behavior? |
| LangGraph | Existing graph, nodes and state design | Which layer owns checkpoints, retries and interrupts? |
| OpenAI Agents SDK | Existing agents, handoffs and tracing conventions | Are tool and approval events mapped without loss? |
| Google ADK | Existing Google agent implementation | Are session state and artifacts durably represented? |
| HTTP/OpenAPI tool | Server-side call without custom worker code | Where are credentials, rate limits and response schemas enforced? |
| MCP tool | Reuse an MCP server’s capability surface | Can each exposed method be scoped and audited independently? |
Credentials and stored execution data
Agentspan supports provider keys through environment configuration and server-executed HTTP, OpenAPI and MCP tools. Central execution can reduce secrets copied into every worker, but it also concentrates authority. Use a secret manager, short-lived credentials, per-environment identities and outbound allowlists. Never place credentials inside prompts, tool schemas or persisted results.
Execution history can contain customer text, retrieved documents, source code, model responses, tool arguments and errors. Decide which fields are redacted before storage, who can search or replay runs, how tenants are separated, and how deletion requests propagate to backups and observability exports. Encrypt transport and storage, audit read access, and test restoration rather than assuming persistence equals recoverability.
Observability that leads to action
Raw traces are useful only if they answer operational questions. Attach a correlation ID across the trigger, workflow, model calls and external mutations. Record model/version, prompt-policy version, token counts, tool latency, retry reason, approval delay and terminal classification. Avoid high-cardinality secrets in labels.
| Metric | Why it matters | Suggested alert |
|---|---|---|
| Successful business outcomes | Separates completed workflows from correct results | Drop against task-specific baseline |
| Duplicate side effects | Detects broken idempotency | Any confirmed duplicate for critical tools |
| Retries per step | Finds unstable tools and hidden cost | Sustained increase by tool/version |
| Approval age | Shows stuck work and operational burden | Past policy SLA or expiry |
| Recovery success | Measures the core durability promise | Any unrecoverable eligible run |
| Cost per accepted outcome | Combines model, compute and reviewer cost | Regression versus control workflow |
Deployment and upgrade checklist
- Pin the SDK, server and Conductor versions; record the compatibility matrix.
- Separate development, staging and production credentials, queues and data stores.
- Back up workflow metadata and test a restore into an isolated environment.
- Set concurrency, token, time, retry and recursion budgets per agent and tenant.
- Configure health checks for server, workers, queues, database and model providers.
- Use canary workers for upgrades and keep old workflow definitions available for in-flight runs.
- Define cancellation semantics: stop future work, revoke credentials and reconcile partial side effects.
- Threat-model prompt injection, SSRF, malicious tool output and over-broad MCP/OpenAPI exposure.
Alternatives and the honest selection boundary
| Option | Choose it when | Tradeoff |
|---|---|---|
| Agentspan | You want agent-specific APIs over Conductor, self-hosting and integrations | New control plane and evolving project surface |
| LangGraph persistence | Your application is already deeply graph-shaped | You own more production orchestration choices |
| Temporal | The organization already operates durable workflows at scale | Agent adapters and replay-safe code require engineering |
| Conductor directly | You need general workflow primitives beyond agents | Less agent-specific convenience |
| Restate or DBOS patterns | You want durable functions/transactions close to application code | Different ecosystem and integration model |
| Queue + database state machine | Workflow is small, deterministic and stable | Lowest dependency count, but custom recovery and UI work |
| Managed agent platform | Fast operation matters more than infrastructure control | Vendor, data and customization constraints |
Do not add a durable runtime merely because a workflow uses an LLM. A short synchronous assistant with no side effects may need only request logging and retries. Agentspan becomes compelling when runs are long, approvals wait beyond a process lifetime, events trigger work, or recovery history is a product requirement.
A two-week evaluation plan
Week one should establish a control workflow and integration. Select one bounded job with three to ten steps, one approval and a reversible external write. Measure uninterrupted success and cost, then inject crashes. Week two should focus on hostile and operational cases: duplicate events, delayed approvals, malformed tool output, provider rate limits, worker replacement, server restart and an upgrade with an in-flight run.
Promote only if another engineer can reproduce deployment and recovery from written instructions, every mutating tool has a tested side-effect policy, sensitive history is governed, and the accepted-outcome rate improves enough to justify the server and on-call burden.
Frequently asked questions
Is Agentspan an agent framework?
It includes an Agent API, but its differentiator is the durable runtime under the agent. It can also run agents built with supported external frameworks.
What is the execution engine?
The project states that agent definitions compile to workflows on Conductor, which supplies durable state, history, retries and workflow primitives.
Can it self-host?
Yes. The official site describes it as MIT licensed and self-hostable. Operators still need to validate dependencies, data stores, upgrades and support expectations.
Does crash recovery prevent duplicate writes?
No. Durable orchestration reduces lost state, but external writes still require idempotency, reconciliation or compensation.
Are approvals automatically secure?
No. Teams must define authentication, authorization, argument binding, expiry, segregation of duties and audit retention.
Does it eliminate the need for an agent framework?
No. It can complement existing agent definitions. Choose one clear owner for state, retries and interrupts to avoid conflicting semantics.
What should the first production workload be?
A bounded, reversible, low-sensitivity workflow with measurable success and clear escalation—not payments, production changes or broad data access.
Primary sources
- Official Agentspan site and quickstart
- Official documentation
- Official architecture and durability explanation
- Agent execution concepts
- Tool types and server-side execution
- Supported model providers and configuration
- CLI, approvals and execution history
- Official source repository
- OWASP guidance for LLM application risks
Last reviewed July 25, 2026. Agentspan is evolving quickly. Verify the exact SDK/server release, license, framework adapter and deployment instructions before adopting it.
