### Run Agent Example with UVicorn

Source: https://github.com/agentspan-ai/agentspan/blob/main/sdk/python/examples/quickstart/README.md

Use this command to execute any of the quickstart Python examples. Ensure you have `uvicorn` installed.

```bash
uv run python quickstart/01_basic_agent.py
```

--------------------------------

### Agentspan CLI Quickstart Commands

Source: https://github.com/agentspan-ai/agentspan/blob/main/cli/README.md

A sequence of commands to get started with the Agentspan CLI, including checking dependencies, setting API keys, starting the server, and running an agent.

```bash
# Check system dependencies
agentspan doctor

# Set your LLM provider API key
export OPENAI_API_KEY=sk-...

# Start the runtime server (downloads automatically on first run)
agentspan server start

# Create an agent config
agentspan agent init mybot

# Run an agent
agentspan agent run --config mybot.yaml "What is the weather in NYC?"
```

--------------------------------

### Install and Configure Agentspan

Source: https://context7.com/agentspan-ai/agentspan/llms.txt

Install the Python SDK and CLI, verify the setup, set an LLM provider key, and start the Agentspan server.

```bash
pip install agentspan

# Verify setup
agentspan doctor

# Set an LLM provider key
export OPENAI_API_KEY=sk-...

# Start the server (downloads ~50 MB JAR on first run, cached thereafter)
agentspan server start
# UI and API available at http://localhost:6767
```

--------------------------------

### Run AgentSpan Example

Source: https://github.com/agentspan-ai/agentspan/blob/main/sdk/typescript/examples/quickstart/README.md

Execute any AgentSpan quickstart example using npx and tsx.

```bash
npx tsx quickstart/01-basic-agent.ts
```

--------------------------------

### Install AgentSpan and Start Server

Source: https://github.com/agentspan-ai/agentspan/blob/main/sdk/python/examples/blog_and_videos/random/07_brainstorm_random_blog.md

Install the AgentSpan library and start the local server. Access the visual dashboard at localhost:6767.

```bash
pip install agentspan
agentspan server start
```

--------------------------------

### Install SDK Dependencies

Source: https://github.com/agentspan-ai/agentspan/blob/main/sdk/typescript/examples/README.md

Commands to install dependencies for the core SDK examples or framework-specific examples.

```bash
cd sdk/typescript
npm install
```

```bash
npm install @agentspan-ai/sdk zod
```

```bash
cd adk && npm install
```

```bash
cd langgraph && npm install
```

```bash
cd openai && npm install
```

```bash
cd vercel-ai && npm install
```

--------------------------------

### Quick Start Configuration

Source: https://github.com/agentspan-ai/agentspan/blob/main/sdk/python/examples/langgraph/README.md

Sets up environment variables for Agentspan server URL and OpenAI API key. Executes the 'hello world' example using `uv run`.

```bash
export AGENTSPAN_SERVER_URL=http://localhost:6767/api
export OPENAI_API_KEY=sk-...

cd sdk/python
uv run python examples/langgraph/01_hello_world.py
```

--------------------------------

### Quick Start: Running a Basic Agent

Source: https://github.com/agentspan-ai/agentspan/blob/main/sdk/java/README.md

This example demonstrates how to create a simple agent, run it with a prompt, and print the result. Ensure you have configured your Agentspan server connection.

```java
import ai.agentspan.Agent;
import ai.agentspan.Agentspan;
import ai.agentspan.model.AgentResult;

public class Main {
    public static void main(String[] args) {
        Agent agent = Agent.builder()
            .name("assistant")
            .model("openai/gpt-4o")
            .instructions("You are a helpful assistant.")
            .build();

        AgentResult result = Agentspan.run(agent, "What is the capital of France?");
        result.printResult();
        Agentspan.shutdown();
    }
}
```

--------------------------------

### Install Agentspan CLI and Start Server

Source: https://github.com/agentspan-ai/agentspan/blob/main/deployment/README.md

Installs the Agentspan CLI and starts the server using SQLite for local development. Ensure your OPENAI_API_KEY is set.

```bash
curl -fsSL https://raw.githubusercontent.com/agentspan-ai/agentspan/main/cli/install.sh | sh

export OPENAI_API_KEY=sk-...
agentspan server start
```

--------------------------------

### Simplest Agent: Hello World

Source: https://github.com/agentspan-ai/agentspan/blob/main/sdk/python/examples/langgraph/README.md

Demonstrates the most basic agent setup using `create_agent` without any tools. This serves as a starting point for understanding agent creation.

```python
from langgraph.graph import StateGraph
from agentspan.agents import create_agent

agent = create_agent(
    name="hello-world-agent",
    # No tools or specific instructions provided, relies on LLM's base capabilities
)

workflow = StateGraph(agent.state)
workflow.add_node("agent", agent.run)
workflow.set_entry_point("agent")

app = workflow.compile()

# Example of running the agent (actual execution would involve input)
# result = app.invoke({"messages": [HumanMessage(content="Hello!")]})
# print(result)
```

--------------------------------

### Run Example

Source: https://github.com/agentspan-ai/agentspan/blob/main/sdk/typescript/examples/README.md

Commands to execute core SDK examples or framework-specific examples using `npx tsx`.

```bash
# Core SDK examples (run from sdk/typescript/)
npx tsx examples/01-basic-agent.ts
npx tsx examples/15-agent-discussion.ts
```

```bash
# Framework-specific examples
cd adk && npx tsx 01-basic-agent.ts
cd langgraph && npx tsx 01-hello-world.ts
cd openai && npx tsx 01-basic-agent.ts
```

--------------------------------

### Run Basic TypeScript SDK Example

Source: https://github.com/agentspan-ai/agentspan/blob/main/docs/design/plans/2026-03-24-typescript-sdk-implementation.md

Execute a basic agent example using the TypeScript SDK. Ensure you have Node.js and npm installed.

```bash
npx tsx examples/01-basic-agent.ts
```

--------------------------------

### Install Agentspan SDK

Source: https://github.com/agentspan-ai/agentspan/blob/main/sdk/python/examples/README.md

Installs the core Agentspan SDK using pip. This is the primary command for running the core examples.

```bash
uv pip install agentspan
```

--------------------------------

### Run All Configured Examples

Source: https://github.com/agentspan-ai/agentspan/blob/main/sdk/python/validation/README.md

Executes all example runs defined in the TOML configuration file.

```bash
python3 -m validation.scripts.run_examples --config validation/runs.toml
```

--------------------------------

### Agent Introductions Example

Source: https://github.com/agentspan-ai/agentspan/blob/main/sdk/python/examples/README.md

Shows how agents can introduce themselves before a group discussion using the `introduction` parameter. This helps set context and define roles at the start of an interaction.

```python
python 29_agent_introductions.py
```

--------------------------------

### Example Credential Storage

Source: https://github.com/agentspan-ai/agentspan/blob/main/docs/cli.md

Examples of setting API keys and tokens as credentials.

```bash
agentspan credentials set GITHUB_TOKEN ghp_xxxxxxxxxxxx
```

```bash
agentspan credentials set SEARCH_API_KEY xxx-your-key
```

--------------------------------

### Complete Refund Agent Example with Human Approval

Source: https://github.com/agentspan-ai/agentspan/blob/main/docs/examples/human-in-the-loop.md

This example demonstrates a full agent workflow that includes tools for looking up order and customer details, and a `process_refund` tool that requires human approval. It shows how to start the agent, poll for approval status, and handle user decisions (approve/reject).

```python
import time
from agentspan.agents import Agent, tool, start

# Tools that run automatically
@tool
def get_order(order_id: str) -> dict:
    """Look up an order by ID."""
    return {"order_id": order_id, "amount": 29.99, "status": "delivered"}

@tool
def get_customer(customer_id: str) -> dict:
    """Get customer account details."""
    return {"customer_id": customer_id, "name": "Alex", "email": "alex@example.com"}

# Tool that requires human approval before executing
@tool(approval_required=True)
def process_refund(order_id: str, amount: float) -> dict:
    """Issue a refund. Requires human approval."""
    return {"refunded": True, "order_id": order_id, "amount": amount}

agent = Agent(
    name="refund_agent",
    model="openai/gpt-4o-mini",
    tools=[get_order, get_customer, process_refund],
    instructions="""You handle refund requests.
    1. Look up the order
    2. Look up the customer
    3. Call process_refund — it will pause for human approval automatically
    """,
)

# Start the agent — returns immediately, workflow runs on the server
handle = start(agent, "Customer Alex (cust_001) wants a refund on order ORD-8821")
print(f"Run ID: {handle.execution_id}")

# Poll until the agent reaches the approval checkpoint
for _ in range(60):
    time.sleep(2)
    status = handle.get_status()

    if status.is_waiting:
        print("\n--- Approval required ---")
        print(f"Agent wants to call: process_refund")
        print(f"Order: ORD-8821  Amount: $29.99")

        decision = input("Approve? (y/n): ").strip().lower()
        if decision == "y":
            handle.approve()
            print("Approved. Waiting for agent to complete...")
            result = handle.stream().get_result()
            print("\nResult:", result.output["result"])
        else:
            reason = input("Rejection reason: ").strip()
            handle.reject(reason)
            print("Rejected.")
        break

    if status.is_complete:
        print("Completed:", status.output["result"])
        break
```

--------------------------------

### Preview Example Execution Plan

Source: https://github.com/agentspan-ai/agentspan/blob/main/sdk/python/validation/README.md

Shows the planned execution of examples without actually running them, useful for verification.

```bash
python3 -m validation.scripts.run_examples --config validation/runs.toml --dry-run
```

--------------------------------

### Install Agentspan SDK and CLI

Source: https://github.com/agentspan-ai/agentspan/blob/main/docs/quickstart.md

Installs the Python SDK and the agentspan CLI. Use `uv` for faster installation.

```bash
pip install agentspan
```

```bash
uv pip install agentspan
```

--------------------------------

### Basic Agent Runtime Example

Source: https://github.com/agentspan-ai/agentspan/blob/main/docs/self-hosting.md

A Python example demonstrating how to define an agent and use the AgentRuntime to execute tasks.

```python
from agentspan.agents import Agent, AgentRuntime, tool

@tool
def process_data(input: str) -> str:
    """Process some data."""
    return f"Processed: {input}"

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

with AgentRuntime() as runtime:
    result = runtime.run(agent, "Process this dataset")
    result.print_result()
```

--------------------------------

### run_examples.py CLI Options

Source: https://github.com/agentspan-ai/agentspan/blob/main/sdk/python/validation/README.md

Lists the available command-line options for the `run_examples.py` script, including configuration, execution control, and output management.

```bash
python3 -m validation.scripts.run_examples [options]

Required:
  --config PATH         Path to TOML multi-run config

Options:
  --run NAMES           Comma-separated run names to execute
  --judge               Run LLM judge after execution
  --output-dir DIR      Output directory (default: validation/output/)
  --dry-run             Show plan without executing
  --resume [RUN_DIR]    Resume, skipping completed examples
  --retry-failed [DIR]  Re-run only failed examples
  --list-groups         List available groups and exit
```

--------------------------------

### Install LangChain Dependencies

Source: https://github.com/agentspan-ai/agentspan/blob/main/sdk/python/examples/README.md

Installs necessary packages for LangChain-specific examples, including the core framework, tools, prompts, and an LLM provider.

```bash
uv pip install langchain langchain-core langchain-openai
```

--------------------------------

### REST API: Get Signal Status Request

Source: https://github.com/agentspan-ai/agentspan/blob/main/docs/sdk-design/2026-03-24-agent-signals-design.md

Example of a GET request to retrieve the status of a specific signal using its signalId.

```http
GET /agent/signal/{signalId}/status

Response: 200 OK
{
  "signalId": "uuid-...",
  "executionId": "uuid-...",
  "delivered": true,
  "disposition": "accepted",
  "rejectionReason": null
}
```

--------------------------------

### Run Core SDK Examples

Source: https://github.com/agentspan-ai/agentspan/blob/main/sdk/python/examples/README.md

Execute the core SDK examples to understand basic agent functionalities. Ensure you have the necessary environment variables set for LLM providers.

```bash
python examples/01_basic_agent.py
```

```bash
python examples/15_agent_discussion.py
```

--------------------------------

### Install Google ADK and Agentspan

Source: https://github.com/agentspan-ai/agentspan/blob/main/sdk/python/examples/adk/README.md

Install the necessary Python packages for Google ADK and Agentspan. Pydantic is required for some examples involving structured output.

```bash
uv pip install google-adk agentspan
```

--------------------------------

### Agent Initialization Example

Source: https://github.com/agentspan-ai/agentspan/blob/main/docs/python-sdk/api-reference.md

Demonstrates how to initialize an Agent with a name, model, and basic instructions. The model parameter follows the 'provider/model' format.

```python
# Static
Agent(name="bot", model="openai/gpt-4o", instructions="You are helpful.")
```

--------------------------------

### Install LangGraph and Langchain Core

Source: https://github.com/agentspan-ai/agentspan/blob/main/docs/design/plans/2026-03-18-langgraph-langchain-support.md

Installs the necessary Python packages, 'langgraph' and 'langchain_core', which are prerequisites for running LangGraph examples. This command is typically run in a virtual environment.

```bash
cd sdk/python && uv run python3 -c "import langgraph; import langchain_core; print('OK')"
```

--------------------------------

### Install LangGraph Dependencies

Source: https://github.com/agentspan-ai/agentspan/blob/main/sdk/python/examples/README.md

Installs packages required for LangGraph examples, including the graph library, core components, and an LLM provider. An optional package for multi-model support is also noted.

```bash
uv pip install langgraph langchain-core langchain-openai
```

--------------------------------

### Managing Agent Execution with AgentHandle

Source: https://github.com/agentspan-ai/agentspan/blob/main/docs/concepts/agents.md

Shows how to start an agent, get a handle to its execution, and interact with it.

```APIDOC
## AgentHandle

Returned by `start()`: A handle to a running (or paused) execution:

| Method | Description |
|---|---|
| `get_status()` | Fetch current status → `AgentStatus` |
| `stream().get_result()` | Wait for the result |
| `approve()` | Approve a paused human-in-the-loop task |
| `reject(reason)` | Reject a HITL task with a reason |
| `send(message)` | Send a message to the agent (multi-turn) |
| `pause()` | Pause the execution |
| `resume()` | Resume a paused execution |
| `cancel(reason)` | Cancel the execution |
| `workflow_id` | The execution ID (attribute) |

```python
with AgentRuntime() as runtime:
    handle = runtime.start(agent, "Analyze Q4 reports")

print(handle.workflow_id)     # Store this to reconnect later

# Poll status
status = handle.get_status()
if status.is_waiting:
    handle.approve()
elif status.is_complete:
    print(status.output)
```
```

--------------------------------

### Build and Start Server

Source: https://github.com/agentspan-ai/agentspan/blob/main/docs/design/plans/2026-03-30-agent-api-ui-migration.md

Compile the server application using Gradle and then run the generated JAR file. The server is started in the background.

```bash
cd server && ./gradlew bootJar
java -jar build/libs/agentspan-runtime.jar &
```

--------------------------------

### Run Framework-Specific Examples

Source: https://github.com/agentspan-ai/agentspan/blob/main/sdk/python/examples/README.md

Explore examples tailored for specific frameworks like Langchain, Langgraph, OpenAI, and ADK. These showcase integration and specialized use cases.

```bash
python examples/langchain/01_hello_world.py
```

```bash
python examples/langgraph/01_hello_world.py
```

```bash
python examples/openai/01_basic_agent.py
```

```bash
python examples/adk/01_basic_agent.py
```

--------------------------------

### REST API: Get Pending Signals Request

Source: https://github.com/agentspan-ai/agentspan/blob/main/docs/sdk-design/2026-03-24-agent-signals-design.md

Example of a GET request for framework workers to retrieve pending signals for a given agent execution. This endpoint atomically returns and marks signals as delivered.

```http
GET /agent/{executionId}/signals/pending

Response: 200 OK
{
  "signals": [
    {"signalId": "uuid-1", "message": "...", "sender": "...", "priority": "normal"}
  ]
}
```

--------------------------------

### Agent Start HTTP Payload Example

Source: https://github.com/agentspan-ai/agentspan/blob/main/docs/sdk-design/2026-03-23-multi-language-sdk-design.md

The POST /agent/start payload includes sessionId, media, idempotencyKey, timeoutSeconds, and credentials fields.

```json
{
  "agentConfig": { ... },
  "prompt": "user input",
  "sessionId": "",
  "media": [],
  "idempotencyKey": "optional-key",
  "timeoutSeconds": 300,
  "credentials": ["CRED_A", "CRED_B"]
}
```

--------------------------------

### Running Agentspan Examples

Source: https://github.com/agentspan-ai/agentspan/blob/main/sdk/typescript/examples/adk/README.md

This command demonstrates how to set up environment variables for API keys and server URLs, and then execute a specific example script using `tsx`.

```bash
export AGENTSPAN_SERVER_URL=...
# For Gemini models:
export GOOGLE_API_KEY=...
# Or override with OpenAI:
export AGENTSPAN_LLM_MODEL=openai/gpt-4o-mini
export OPENAI_API_KEY=...

cd sdk/typescript
npx tsx examples/adk/01-basic-agent.ts
```

--------------------------------

### Tool Guardrail Setup

Source: https://github.com/agentspan-ai/agentspan/blob/main/docs/guardrails.md

Configure a guardrail to check tool inputs before execution. This example uses a 'no_sql_injection' guardrail that raises a ValueError on failure.

```python
sql_guard = Guardrail(
    no_sql_injection,
    position="input",     # check BEFORE tool executes
    on_fail="raise",      # hard block
)

@tool(guardrails=[sql_guard])
def run_query(query: str) -> str:
    """Execute a database query."""
    ...
```

--------------------------------

### Copy Runtime Configuration Example

Source: https://github.com/agentspan-ai/agentspan/blob/main/ui/README.md

Copies the example runtime configuration file to public/context.js. This file is loaded at startup and is not bundled.

```bash
cp public/context.js.example public/context.js
```

--------------------------------

### Integrate Human Review with Agent Runtime

Source: https://github.com/agentspan-ai/agentspan/blob/main/docs/design/GUARDRAIL_GUIDE.md

Start an agent, poll for human review pauses, and approve the task. This example demonstrates the workflow for human-in-the-loop.

```python
with AgentRuntime() as runtime:
    handle = runtime.start(agent, "Give me investment advice.")

    # Poll until the execution pauses
    import time
    while True:
        status = handle.get_status()
        if status.is_waiting:
            print("Paused for human review")
            runtime.approve(handle.execution_id)
            break
        if status.is_complete:
            break
        time.sleep(1)

    # Get final result
    status = handle.get_status()
    print(status.output)
```

--------------------------------

### REST API: Resolve Agent Name Request

Source: https://github.com/agentspan-ai/agentspan/blob/main/docs/sdk-design/2026-03-24-agent-signals-design.md

Example of a GET request to resolve agent names to their execution IDs, optionally filtering by status.

```http
GET /agent/resolve?name=researcher&status=RUNNING,PAUSED

Response: 200 OK
{
  "executionIds": ["uuid-1", "uuid-2"],
  "count": 2
}
```

--------------------------------

### Initialize and Start Agentspan with Docker Compose

Source: https://github.com/agentspan-ai/agentspan/blob/main/deployment/docker-compose/README.md

Set up the environment, generate keys, and launch the Agentspan stack.

```bash
cd deployment/docker-compose
cp .env.example .env
# Generate and set the encryption master key
# openssl rand -base64 32
# Set at least one provider key in .env (for example OPENAI_API_KEY)
docker compose up -d
```

--------------------------------

### Run Deploy Command Logic

Source: https://github.com/agentspan-ai/agentspan/blob/main/docs/design/plans/2026-03-27-cli-deploy-command.md

The `runDeploy` function orchestrates the deploy command execution, starting with getting the current working directory and detecting the project language.

```go
func runDeploy(cmd *cobra.Command, args []string) error {
	dir, err := os.Getwd()
	if err != nil {
		return fmt.Errorf("failed to get working directory: %w", err)
	}

	// Step 1: Detect language
	language, err := detectLanguage(dir, deployLanguage)

```

--------------------------------

### Install Dependencies and Verify Build

Source: https://github.com/agentspan-ai/agentspan/blob/main/docs/design/plans/2026-03-24-typescript-sdk-implementation.md

Navigate to the SDK directory, install npm dependencies, and run the TypeScript compiler to ensure the project is set up correctly.

```bash
cd sdk/typescript && npm install && npx tsc --noEmit
```

--------------------------------

### Start Development Server

Source: https://github.com/agentspan-ai/agentspan/blob/main/docs/design/plans/2026-03-21-credentials-ui.md

Start the development server to manually test the Credentials UI. This involves verifying navigation, dialogs, and data manipulation.

```bash
cd ui && npm run dev
```

--------------------------------

### Run Google ADK Integration Example

Source: https://github.com/agentspan-ai/agentspan/blob/main/sdk/typescript/README.md

Execute an example demonstrating integration with Google ADK. This command is used to test agents that interact with Google's platform services.

```bash
npx tsx examples/adk/01-basic-agent.ts
```

--------------------------------

### Run LangChain Integration Example

Source: https://github.com/agentspan-ai/agentspan/blob/main/sdk/typescript/README.md

Execute an example demonstrating integration with LangChain. This command is used to verify the interoperability and data flow between Agentspan and LangChain components.

```bash
npx tsx examples/langchain/01-basic-agent.ts
```

--------------------------------

### Quick Start Helm Deployment

Source: https://github.com/agentspan-ai/agentspan/blob/main/deployment/helm/README.md

Installs or upgrades the Agentspan Helm chart with default settings, including generating a master key and setting a placeholder for the PostgreSQL password.

```bash
helm upgrade --install agentspan ./deployment/helm/agentspan \
  --namespace agentspan \
  --create-namespace \
  --set secrets.masterKey=$(openssl rand -base64 32) \
  --set secrets.postgresPassword='change-me'
```

--------------------------------

### Run Vercel AI SDK Integration Example

Source: https://github.com/agentspan-ai/agentspan/blob/main/sdk/typescript/README.md

Execute an example demonstrating integration with the Vercel AI SDK. This command is used for testing the compatibility and functionality between Agentspan and Vercel AI.

```bash
npx tsx examples/vercel-ai/01-basic-agent.ts
```

--------------------------------

### Run All Validation Examples

Source: https://github.com/agentspan-ai/agentspan/blob/main/sdk/python/CLAUDE.md

Execute all validation examples using the `run_examples` script with a specified TOML configuration file. Ensure the config file is present and correctly formatted.

```bash
uv run python3 -m validation.scripts.run_examples --config runs.toml
```

--------------------------------

### Clone Agentspan Repository and Setup Python Environment

Source: https://github.com/agentspan-ai/agentspan/blob/main/README.md

Clone the Agentspan repository, navigate to the Python SDK directory, create a virtual environment, install development dependencies, and run tests.

```bash
git clone https://github.com/agentspan-ai/agentspan.git
cd agentspan/sdk/python
uv venv && source .venv/bin/activate
uv pip install -e ".[dev]"
pytest
```

--------------------------------

### Fix SSL Certificate Errors on macOS

Source: https://github.com/agentspan-ai/agentspan/blob/main/docs/python-sdk/api-reference.md

This command installs SSL certificates for Python on macOS, which is necessary for examples making outbound HTTPS calls. Replace '3.12' with your specific Python version.

```bash
# Replace 3.12 with your Python version
/Applications/Python\ 3.12/Install\ Certificates.command
```

--------------------------------

### Example Usage of NewTool in Go

Source: https://github.com/agentspan-ai/agentspan/blob/main/docs/sdk-design/go.md

Demonstrates the practical application of `NewTool` by creating a `searchTool` with a specific handler, credentials, and a timeout. This shows how to pass functional options to customize tool creation.

```go
searchTool := agentspan.NewTool(
    "web_search",
    "Search the web for recent articles.",
    func(ctx context.Context, input map[string]any, tc *agentspan.ToolContext) (any, error) {
        query := input["query"].(string)
        return map[string]any{"results": []string{query + " result"}}, nil
    },
    agentspan.WithCredentials("SEARCH_API_KEY"),
    agentspan.WithToolTimeout(30),
)
```

--------------------------------

### Implement Agent Callbacks in Java

Source: https://github.com/agentspan-ai/agentspan/blob/main/docs/sdk-design/java.md

Extend the `CallbackHandler` class to implement methods for agent lifecycle events such as start, end, model interactions, and tool usage. This example shows logging for agent and model events.

```java
public class PublishingCallbackHandler extends CallbackHandler {
    @Override
    public void onAgentStart(String agentName, Map<String, Object> kwargs) {
        callbackLog.log("before_agent", Map.of("agent_name", agentName));
    }
    @Override
    public void onAgentEnd(String agentName, Map<String, Object> kwargs) {
        callbackLog.log("after_agent", Map.of("agent_name", agentName));
    }
    @Override
    public void onModelStart(String agentName, List<Map<String, Object>> messages, Map<String, Object> kwargs) {
        callbackLog.log("before_model", Map.of("message_count", messages.size()));
    }
    @Override
    public void onModelEnd(String agentName, String response, Map<String, Object> kwargs) {
        callbackLog.log("after_model", Map.of("result_length", response.length()));
    }
    @Override
    public void onToolStart(String agentName, String toolName, Map<String, Object> kwargs) {
        callbackLog.log("before_tool", Map.of("tool_name", toolName));
    }
    @Override
    public void onToolEnd(String agentName, String toolName, Map<String, Object> kwargs) {
        callbackLog.log("after_tool", Map.of("tool_name", toolName));
    }
}
```

--------------------------------

### Run Existing Credential Example

Source: https://github.com/agentspan-ai/agentspan/blob/main/docs/design/plans/2026-03-22-universal-credential-support.md

Execute a pre-existing Python example that demonstrates credential usage with the AgentSpan SDK. This command includes a timeout to prevent indefinite execution.

```bash
timeout 90 uv run python examples/16d_credentials_gh_cli.py
```

--------------------------------

### Maven Project Setup

Source: https://github.com/agentspan-ai/agentspan/blob/main/docs/sdk-design/java.md

Configure your Maven project with the necessary Agentspan SDK module coordinates and dependencies. This example includes Jackson for JSON serialization, Apache HttpClient for Java 8, and Orkes Conductor client.

```xml
<project>
  <groupId>dev.agentspan</groupId>
  <artifactId>agentspan-sdk</artifactId>
  <version>0.1.0</version>

  <properties>
    <maven.compiler.source>8</maven.compiler.source>
    <maven.compiler.target>8</maven.compiler.target>
    <jackson.version>2.17.0</jackson.version>
  </properties>

  <dependencies>
    <!-- JSON serialization -->
    <dependency>
      <groupId>com.fasterxml.jackson.core</groupId>
      <artifactId>jackson-databind</artifactId>
      <version>${jackson.version}</version>
    </dependency>
    <dependency>
      <groupId>com.fasterxml.jackson.datatype</groupId>
      <artifactId>jackson-datatype-jdk8</artifactId>
      <version>${jackson.version}</version>
    </dependency>

    <!-- HTTP client (Java 8 baseline) -->
    <dependency>
      <groupId>org.apache.httpcomponents.client5</groupId>
      <artifactId>httpclient5</artifactId>
      <version>5.3</version>
    </dependency>

    <!-- Conductor client -->
    <dependency>
      <groupId>io.orkes.conductor</groupId>
      <artifactId>orkes-conductor-client</artifactId>
      <version>4.0.1</version>
    </dependency>

    <!-- SLF4J logging -->
    <dependency>
      <groupId>org.slf4j</groupId>
      <artifactId>slf4j-api</artifactId>
      <version>2.0.12</version>
    </dependency>

    <!-- Testing -->
    <dependency>
      <groupId>org.junit.jupiter</groupId>
      <artifactId>junit-jupiter</artifactId>
      <version>5.10.2</version>
      <scope>test</scope>
    </dependency>
  </dependencies>

  <profiles>
    <!-- Java 11+: Use built-in HttpClient instead of Apache -->
    <profile>
      <id>java11</id>
      <activation>
        <jdk>[11,)</jdk>
      </activation>
      <properties>
        <maven.compiler.source>11</maven.compiler.source>
        <maven.compiler.target>11</maven.compiler.target>
      </properties>
    </profile>

    <!-- Java 16+: Enable records -->
    <profile>
      <id>java16</id>
      <activation>
        <jdk>[16,)</jdk>
      </activation>
      <properties>
        <maven.compiler.source>16</maven.compiler.source>
        <maven.compiler.target>16</maven.compiler.target>
      </properties>
    </profile>

    <!-- Java 21+: Enable virtual threads -->
    <profile>
      <id>java21</id>
      <activation>
        <jdk>[21,)</jdk>
      </activation>
      <properties>
        <maven.compiler.source>21</maven.compiler.source>
        <maven.compiler.target>21</maven.compiler.target>
      </properties>
    </profile>
  </profiles>
</project>
```

--------------------------------

### Basic Agent Example

Source: https://github.com/agentspan-ai/agentspan/blob/main/sdk/python/examples/README.md

Demonstrates the simplest possible agent configuration with a single LLM and no tools. This example is concise, requiring only a few lines of code.

```python
python 01_basic_agent.py
```

--------------------------------

### Agentspan Kubernetes Deployment Quick Start

Source: https://github.com/agentspan-ai/agentspan/blob/main/deployment/k8s/README.md

Follow these steps to quickly deploy Agentspan. Ensure you have `kubectl` and `docker` configured, and `ingress-nginx` installed. Edit the secret file with your credentials and master key before running the deploy script.

```bash
# 1. Edit secrets
cp deployment/k8s/agentspan/secret.yaml deployment/k8s/agentspan/secret.yaml.bak
vi deployment/k8s/agentspan/secret.yaml  # set real passwords + API keys

# 2. Generate and set master key
openssl rand -base64 32
# paste the output into secret.yaml under AGENTSPAN_MASTER_KEY

# 3. Deploy
./deployment/k8s/deploy.sh
```

--------------------------------

### Agent Initialization with Different Models

Source: https://github.com/agentspan-ai/agentspan/blob/main/docs/concepts/agents.md

Examples of initializing an Agent with different LLM providers and models.

```python
agent = Agent(name="bot", model="openai/gpt-4o")
```

```python
agent = Agent(name="bot", model="anthropic/claude-sonnet-4-6")
```

```python
agent = Agent(name="bot", model="google_gemini/gemini-2.0-flash")
```

--------------------------------

### Start Agent and Get Handle

Source: https://github.com/agentspan-ai/agentspan/blob/main/docs/concepts/agents.md

Initiate an agent execution and obtain a handle for managing it. The handle allows polling status, approving/rejecting tasks, sending messages, and controlling execution flow. Store the workflow_id to reconnect later.

```python
with AgentRuntime() as runtime:
    handle = runtime.start(agent, "Analyze Q4 reports")

print(handle.workflow_id)     # Store this to reconnect later

# Poll status
status = handle.get_status()
if status.is_waiting:
    handle.approve()
elif status.is_complete:
    print(status.output)
```

--------------------------------

### Full Pipeline Agent Deployment and Execution

Source: https://github.com/agentspan-ai/agentspan/blob/main/docs/sdk-design/kotlin.md

Demonstrates deploying, planning, and streaming a full agent pipeline with human-in-the-loop interaction. Includes event handling for different stages like THINKING, TOOL_CALL, WAITING, and ERROR. Also shows how to retrieve results and token usage.

```kotlin
fun main() = runBlocking {
    val prompt = "Write a comprehensive tech article about quantum computing advances in 2026."

    if (isTracingEnabled()) println("[tracing] OpenTelemetry tracing is enabled")

    AgentRuntime().use {
        runtime ->
        // Deploy (compile + register)
        val deployments = runtime.deploy(fullPipeline)
        deployments.forEach { println("  Deployed: ${it.registeredName}") }

        // Plan (dry-run, no execution)
        runtime.plan(fullPipeline)

        // Stream with HITL — exhaustive when on EventType
        val agentStream = runtime.stream(fullPipeline, prompt)
        val hitlState = mutableMapOf("approved" to 0, "rejected" to 0, "feedback" to 0)

        agentStream.asFlow().collect { event ->
            when (event.type) {
                EventType.THINKING       -> println("[thinking] ${event.content?.take(80)}...")
                EventType.TOOL_CALL      -> println("[tool_call] ${event.toolName}")
                EventType.TOOL_RESULT    -> println("[tool_result] ${event.toolName}")
                EventType.HANDOFF        -> println("[handoff] -> ${event.target}")
                EventType.GUARDRAIL_PASS -> println("[guardrail_pass] ${event.guardrailName}")
                EventType.GUARDRAIL_FAIL -> println("[guardrail_fail] ${event.guardrailName}")
                EventType.MESSAGE        -> println("[message] ${event.content?.take(80)}...")
                EventType.WAITING -> when {
                    hitlState["feedback"] == 0   -> { agentStream.send("Add more details."); hitlState["feedback"] = 1 }
                    hitlState["rejected"] == 0   -> { agentStream.reject("Title needs work"); hitlState["rejected"] = 1 }
                    else                         -> { agentStream.approve(); hitlState["approved"] = hitlState.getValue("approved") + 1 }
                }
                EventType.ERROR -> println("[error] ${event.content}")
                EventType.DONE  -> println("[done] Pipeline complete")
            }
        }

        // Token tracking
        val result = agentStream.getResult()
        result.tokenUsage?.let { println("Total tokens: ${it.totalTokens}") }
    }
    shutdown()
}
```

--------------------------------

### Test New Endpoints with Curl

Source: https://github.com/agentspan-ai/agentspan/blob/main/docs/design/plans/2026-03-30-agent-api-ui-migration.md

Verify the functionality of the new agent API endpoints by using curl to start an execution, retrieve full execution details, and get the task list. Replace '{id}' with an actual execution ID.

```bash
# Start an execution
curl -s http://localhost:6767/api/agent/start \
  -H "Content-Type: application/json" \
  -d '{"agentConfig":{"name":"test","model":"openai/gpt-4o","instructions":"Say hi"},"prompt":"hello"}' \
  | python3 -m json.tool

# Get full execution (new endpoint)
curl -s "http://localhost:6767/api/agent/executions/{id}/full" | python3 -m json.tool

# Get task list (new endpoint)
curl -s "http://localhost:6767/api/agent/executions/{id}/tasks" | python3 -m json.tool
```

--------------------------------

### Start mcp-testkit and agentspan Server

Source: https://github.com/agentspan-ai/agentspan/blob/main/docs/superpowers/specs/2026-04-07-e2e-validation-framework-design.md

Commands to start the mcp-testkit and agentspan server services. mcp-testkit is started with HTTP transport, and the agentspan server is started using its JAR file.

```bash
mcp-testkit --transport http
```

```bash
java -jar ...
```

--------------------------------

### Agent Initialization

Source: https://github.com/agentspan-ai/agentspan/blob/main/docs/python-sdk/api-reference.md

Demonstrates how to initialize an Agent with various configurations like model, memory, tools, and dependencies.

```APIDOC
## Agent Initialization

### Description
Initialize an Agent with core parameters and optional configurations.

### Parameters
- `name` (str): The name of the agent.
- `model` (str): The language model to use (e.g., "openai/gpt-4o").
- `instructions` (Callable[[], str]): A function that returns instructions for the agent.
- `tools` (List[Callable]): A list of decorated functions or `ToolDef` instances.
- `agents` (List[Agent]): A list of sub-agents for multi-agent orchestration.
- `strategy` (str): How sub-agents are orchestrated (e.g., "handoff", "sequential").
- `output_type` (Type[BaseModel]): A Pydantic `BaseModel` subclass for structured output.
- `guardrails` (List[Guardrail]): A list of `Guardrail` instances.
- `memory` (ConversationMemory): Optional `ConversationMemory` for session management.
- `dependencies` (Dict): Objects to inject into tools via `ToolContext`.
- `max_turns` (int): Maximum iterations of the think-act-observe loop.
- `stop_when` (Callable[[dict], bool]): Callable evaluated after each tool call to stop early.

### Example 1: Basic Agent with Memory
```python
from agentspan.agents import Agent, ConversationMemory

memory = ConversationMemory(max_messages=50)
agent = Agent(name="bot", model="openai/gpt-4o", memory=memory)
```

### Example 2: Agent with Tools and Dependencies
```python
from agentspan.agents import Agent

agent = Agent(
    name="bot", model="openai/gpt-4o",
    tools=[query_db], # Assuming query_db is a defined tool
    dependencies={"db": my_database, "user_id": "u-123"}, # Assuming my_database is defined
)
```

### Example 3: Agent with Early Stopping Condition
```python
from agentspan.agents import Agent

def budget_check(ctx):
    return ctx["iteration"] >= 3  # Stop after 3 tool calls

agent = Agent(name="bot", model="openai/gpt-4o", tools=[...], stop_when=budget_check)
```
```

--------------------------------

### Run Streaming Example

Source: https://github.com/agentspan-ai/agentspan/blob/main/docs/typescript-sdk/plan.md

Executes the weather agent example with streaming output enabled, configuring the server URL and LLM model.

```bash
AGENTSPAN_SERVER_URL=http://localhost:6767 \
AGENT_LLM_MODEL=openai/gpt-4o \
node examples/weather-stream.js
```

--------------------------------

### Install Dependencies

Source: https://github.com/agentspan-ai/agentspan/blob/main/sdk/python/examples/langgraph/README.md

Installs the necessary Python packages for LangGraph and Agentspan integration. Ensure you have `uv` installed for optimal performance.

```bash
uv pip install langgraph langchain-core langchain-openai agentspan
```

--------------------------------

### Load and Run a Skill as an Agent

Source: https://github.com/agentspan-ai/agentspan/blob/main/docs/python-sdk/skills.md

Load a skill directory as an Agent and run it using AgentRuntime. This example demonstrates how to execute a skill and print its results, status, and token usage.

```python
from agentspan.agents import skill, AgentRuntime

# Load a skill directory as an Agent
dg = skill("~/.claude/skills/dg", model="openai/gpt-4o")

# Run it like any other agent
with AgentRuntime() as rt:
    result = rt.run(dg, "Review this code for security issues:\n\ndef login(user, pw):\n    return db.execute(f\"SELECT * FROM users WHERE name='{user}'\")")
    print(f"Execution ID: {result.execution_id}")
    print(f"Status: {result.status}")
    print(f"Tokens: {result.token_usage}")
    result.print_result()
```

--------------------------------

### Create a Simple Agent

Source: https://github.com/agentspan-ai/agentspan/blob/main/sdk/python/README.md

Create a basic agent named 'hello' using the 'openai/gpt-4o' model. Run the agent with a simple prompt and print the result.

```python
from agentspan.agents import Agent, AgentRuntime

agent = Agent(name="hello", model="openai/gpt-4o")

with AgentRuntime() as runtime:
    result = runtime.run(agent, "Say hello and tell me a fun fact.")
    result.print_result()
```

--------------------------------

### Install Dependencies with pnpm

Source: https://github.com/agentspan-ai/agentspan/blob/main/ui/README.md

Installs project dependencies using pnpm. Ensure Node.js 22+ and pnpm 10.32.0 are installed.

```bash
pnpm install
```

--------------------------------

### Install Dependencies

Source: https://github.com/agentspan-ai/agentspan/blob/main/sdk/python/examples/openai/README.md

Install the necessary Python packages for running OpenAI agents with the Conductor runtime. Ensure you have `openai-agents` and `agentspan` installed.

```bash
uv pip install openai-agents agentspan
```