github.com/agentspan-ai/agentspan @v0.4.0

<img src="https://github.com/agentspan-ai/agentspan/raw/v0.4.0/docs/assets/agentspan-logo-light.png" alt="Agentspan" width="360">

AI agents that don't die when your process does.

Docs • Quickstart • 180+ Examples • Discord • API Reference

⭐ If you find Agentspan useful, give us a star — it helps others find the project!

https://github.com/user-attachments/assets/dd4b720d-d11c-42e8-93a6-875c5a740fd8

Agentspan is a durable runtime for AI agents, built for Conductor. Three pillars:

Long-running agents — Write an agent; it runs as long as it needs to. Minutes, hours, or until a human approves the next step. No timeout by default. If your worker process crashes, the server resumes from the last completed step when a new worker connects.

Dynamic agents (Plan-Execute) — The LLM decides what to do at runtime; Conductor locks it in and executes it deterministically. The planner emits a JSON plan once; the server compiles it into an immutable Conductor sub-workflow — no LLM randomness in orchestration, retries, or parallelism. Dynamic agents can call existing Conductor workflows as steps, bridging AI with your existing automation. → Strategy.PLAN_EXECUTE · works across Python, TypeScript, Java, C#

Event-driven agents — Trigger agents from cron schedules, Kafka topics, SQS queues, AMQP messages, webhooks, and database events. Agentspan runs on Conductor, so every event source Conductor supports is available to agents. Each trigger is a durable execution with full history. → deploy(agent, schedules=[Schedule(cron="0 0 9 * * MON-FRI")]) · Conductor event handlers

Quickstart (60 seconds)

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/agentspan-ai/agentspan/main/cli/install.sh | sh

# Windows (PowerShell)
irm https://raw.githubusercontent.com/agentspan-ai/agentspan/main/cli/install.ps1 | iex

Install SDKs

Build on Agentspan with the Conductor Agent SDK, available for Python, TypeScript/JavaScript, and C#/.NET:

# Python
pip install conductor-agent-sdk

# TypeScript / JavaScript
npm install @conductor-oss/conductor-agent-sdk

# C# / .NET
dotnet add package conductor-agent-sdk

export OPENAI_API_KEY=sk-...   # or any supported provider
agentspan server start         # runs on localhost:6767 with UI

# hello.py — run with: python hello.py
from conductor.ai.agents import Agent, AgentRuntime, tool

@tool
def get_weather(city: str) -> str:
    """Get current weather for a city."""
    return f"72F and sunny in {city}"

agent = Agent(name="weatherbot", model="openai/gpt-4o", tools=[get_weather])

with AgentRuntime() as runtime:
    result = runtime.run(agent, "What's the weather in NYC?")
    result.print_result()

Open http://localhost:6767 to see the visual execution UI.

Alternative CLI install methods

# npm
npm install -g @agentspan-ai/agentspan

# Windows — CMD / double-click
curl -fsSL https://raw.githubusercontent.com/agentspan-ai/agentspan/main/cli/install.bat -o install.bat && install.bat

# From source
cd cli && go build -o agentspan .

# Verify setup
agentspan doctor

All supported LLM providers (15+)

Why Agentspan?

Agentspan is the execution layer, not the replacement. Use native Agentspan, or bring LangGraph, the OpenAI Agents SDK, or Google ADK — pass your existing agent to runtime.run() and it gains crash recovery, human-in-the-loop pauses, and full execution history. Your definitions stay unchanged.

What makes it different (detailed)

1. True durable execution — Your agent compiles to a server-side execution. Kill the process — the agent keeps running. Poll for results from anywhere.

2. Cross-process agent access — Every agent has an execution ID. Check status, stream events, approve tool calls, pause, resume, or cancel from any process, any machine.

3. Distributed workers in any language — Tools execute as distributed tasks. Write workers in Python, Java, Go, or any language. Scale each tool independently.

4. One primitive — Everything is an Agent. Single agents, multi-agent teams, nested hierarchies — one class.

5. Real human-in-the-loop — @tool(approval_required=True) pauses the execution durably. Approve days later, from any machine.

6. Production guardrails — Custom functions, regex, or LLM judges. Four failure modes: retry, raise, fix, or human escalation.

7. Server-side tools — HTTP endpoints and MCP servers execute as server-side tasks. No worker needed. MCP auto-discovered at compile time.

8. Full observability — Prometheus metrics, visual execution UI, execution history, token usage tracking. OpenTelemetry available (opt-in via config).

9. Framework compatible — Works with Google ADK, OpenAI Agents SDK, LangChain, and LangGraph. 180+ examples.

Code Examples

Agent with Tools

from conductor.ai.agents import Agent, AgentRuntime, tool

@tool
def get_weather(city: str) -> dict:
    """Get current weather for a city."""
    return {"city": city, "temp": 72, "condition": "Sunny"}

@tool
def calculate(expression: str) -> dict:
    """Evaluate a math expression."""
    return {"result": eval(expression)}

agent = Agent(
    name="assistant",
    model="openai/gpt-4o",
    tools=[get_weather, calculate],
    instructions="You are a helpful assistant.",
)

with AgentRuntime() as runtime:
    result = runtime.run(agent, "What's the weather in NYC? Also, what's 42 * 17?")
    result.print_result()

Structured Output

from pydantic import BaseModel
from conductor.ai.agents import Agent, AgentRuntime, tool

class WeatherReport(BaseModel):
    city: str
    temperature: float
    condition: str
    recommendation: str

@tool
def get_weather(city: str) -> dict:
    """Get weather data for a city."""
    return {"city": city, "temp_f": 72, "condition": "Sunny", "humidity": 45}

agent = Agent(name="reporter", model="openai/gpt-4o", tools=[get_weather], output_type=WeatherReport)

with AgentRuntime() as runtime:
    result = runtime.run(agent, "What's the weather in NYC?")
    report: WeatherReport = result.output  # Fully typed

Credential Management

Store API keys and secrets once on the server. Tools resolve them automatically at runtime — no .env files, no hardcoded keys, no secrets in git.

Step 1: Store credentials on the server

agentspan credentials set GITHUB_TOKEN ghp_xxxxxxxxxxxx
agentspan credentials set SEARCH_API_KEY xxx-your-key

Credentials are encrypted at rest (AES-256-GCM). List them with agentspan credentials list.

Step 2: Declare which credentials a tool needs

from conductor.ai.agents import Agent, AgentRuntime, tool, get_credential

# Default: tool runs in isolated subprocess with credentials as env vars
@tool(credentials=["GITHUB_TOKEN"])
def list_repos(username: str) -> dict:
    """List GitHub repos."""
    import os
    token = os.environ["GITHUB_TOKEN"]  # Auto-injected by the runtime
    return {"repos": ["repo1", "repo2"]}

# Alternative: access credentials in-process (no subprocess)
@tool(isolated=False, credentials=["SEARCH_API_KEY"])
def search(query: str) -> dict:
    """Search using API key."""
    key = get_credential("SEARCH_API_KEY")  # Resolve from server at runtime
    return {"results": ["result1"]}

Step 3: Run — credentials resolve automatically

agent = Agent(
    name="github_helper",
    model="openai/gpt-4o",
    tools=[list_repos, search],
    credentials=["GITHUB_TOKEN"],  # Agent-level credentials (shared with all tools)
)

with AgentRuntime() as runtime:
    result = runtime.run(agent, "List my GitHub repos and search for AI papers")
    result.print_result()

Credentials work with every tool type:

from conductor.ai.agents import http_tool, mcp_tool

# HTTP tools: server substitutes ${NAME} in headers at runtime
api = http_tool(
    name="weather_api", description="Get weather data",
    url="https://api.weather.com/v1/current",
    headers={"Authorization": "Bearer ${WEATHER_KEY}"},
    credentials=["WEATHER_KEY"],
)

# MCP tools: credentials passed to MCP server connection
github = mcp_tool(server_url="http://localhost:3001/mcp", credentials=["GITHUB_TOKEN"])

No credentials leave the server unencrypted. Workers resolve them via scoped execution tokens that expire with the execution. See the 11 credential examples (16_*.py through 16k_*.py) for every mode: isolated subprocess, in-process, CLI tools, HTTP headers, MCP, and framework passthrough.

Multi-Agent Handoffs

from conductor.ai.agents import Agent, AgentRuntime, tool

@tool
def check_balance(account_id: str) -> dict:
    """Check account balance."""
    return {"account_id": account_id, "balance": 5432.10}

billing = Agent(name="billing", model="openai/gpt-4o",
                instructions="Handle billing inquiries.", tools=[check_balance])
technical = Agent(name="technical", model="openai/gpt-4o",
                  instructions="Handle technical issues.")

support = Agent(
    name="support", model="openai/gpt-4o",
    instructions="Route customer requests to the right team.",
    agents=[billing, technical],
    strategy="handoff",
)

with AgentRuntime() as runtime:
    result = runtime.run(support, "What's the balance on account ACC-123?")
    result.print_result()

Pipeline Composition

```python from conductor.ai.agents import Agent, AgentRuntime

researcher = Agent(name="researcher", model="openai/gpt-4o", instructions="Research the topic and provide key facts.") writer = Agent(name="writer", model="openai/gpt-4o", instructions="Write an engaging article from the research.") editor = Agent(name="editor", model="openai/gpt-4o", instructions="Polish the article for publication.")

pipeline = researcher >> writer >> editor

with AgentRuntime() as runtime: result = runtime.run(pipeline, "AI agents in software development")