> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://respan.ai/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://respan.ai/docs/_mcp/server.

# AgentSpec (tracing)

> Trace AgentSpec agent workflows with Respan — auto-instrumented spans, gateway routing, and full observability.

[Open Agent Specification (Agent Spec)](https://oracle.github.io/agent-spec/development/docs_home.html) (`pyagentspec`) is Oracle's open specification and Python SDK for defining and running agentic systems. It provides a portable way to describe agents, models, and workflows across runtimes. Respan gives you full observability over every spec execution, model call, and tool invocation — and gateway routing through the OpenAI-compatible Respan endpoint.

#### Set up Respan

Create an account at [platform.respan.ai](https://platform.respan.ai) and grab an [API key](https://platform.respan.ai/platform/gateway/api-keys).

Run `npx @respan/cli setup` to set up with your coding agent.

#### Use Respan Gateway

See [AgentSpec gateway setup](/docs/integrations/gateway/agent-spec) to route this integration through the Respan gateway.

#### Example projects

* [Example projects root](https://github.com/respanai/respan-example-projects)

## Setup

#### Install packages

```bash
pip install respan-ai respan-instrumentation-agentspec "pyagentspec[langgraph]"
```

#### Set environment variables

```bash
export OPENAI_API_KEY="YOUR_OPENAI_API_KEY"
export RESPAN_API_KEY="YOUR_RESPAN_API_KEY"
```

`OPENAI_API_KEY` is used for LLM requests. `RESPAN_API_KEY` is used to export traces to Respan.

#### Initialize and run

```python
from pyagentspec.adapters.langgraph import AgentSpecLoader
from pyagentspec.agent import Agent
from pyagentspec.llms import OpenAiConfig
from respan import Respan
from respan_instrumentation_agentspec import AgentSpecInstrumentor

respan = Respan(
    app_name="agentspec-haiku-agent",
    instrumentations=[
        AgentSpecInstrumentor(workflow_name="agentspec_haiku_agent")
    ],
)

try:
    agent = Agent(
        name="haiku_assistant",
        description="A helpful assistant that writes haikus.",
        llm_config=OpenAiConfig(name="openai", model_id="gpt-4.1-nano"),
        system_prompt="You are a helpful assistant. Respond only with a haiku.",
    )

    langgraph_agent = AgentSpecLoader().load_component(agent)

    result = langgraph_agent.invoke(
        input={"messages": [{"role": "user", "content": "Write a haiku about recursion."}]}
    )
    print(result["messages"][-1].content)
finally:
    respan.shutdown()
```

#### View your trace

Open the [Traces page](https://platform.respan.ai/platform/traces) to see your AgentSpec workflow with specification execution, tool calls, and LLM generations.

## Configuration

| Parameter             | Type           | Default | Description                                                           |
| --------------------- | -------------- | ------- | --------------------------------------------------------------------- |
| `api_key`             | `str \| None`  | `None`  | Falls back to `RESPAN_API_KEY` env var.                               |
| `base_url`            | `str \| None`  | `None`  | Falls back to `RESPAN_BASE_URL` env var.                              |
| `instrumentations`    | `list`         | `[]`    | Plugin instrumentations to activate (e.g. `AgentSpecInstrumentor()`). |
| `customer_identifier` | `str \| None`  | `None`  | Default customer identifier for all spans.                            |
| `metadata`            | `dict \| None` | `None`  | Default metadata attached to all spans.                               |
| `environment`         | `str \| None`  | `None`  | Environment tag (e.g. `"production"`).                                |

`AgentSpecInstrumentor(workflow_name="...")` sets the Respan workflow name and
the root AgentSpec trace span name, making each run easy to identify in the
Traces page.

## Attributes

### In Respan()

Set defaults at initialization — these apply to all spans.

```python
from respan import Respan
from respan_instrumentation_agentspec import AgentSpecInstrumentor

respan = Respan(
    instrumentations=[
        AgentSpecInstrumentor(workflow_name="agentspec_support_request")
    ],
    customer_identifier="user_123",
    metadata={"service": "agentspec-api", "version": "1.0.0"},
)
```

### With propagate_attributes

Override per-request using a context scope.

```python
from respan import Respan, propagate_attributes
from respan_instrumentation_agentspec import AgentSpecInstrumentor

respan = Respan(
    instrumentations=[
        AgentSpecInstrumentor(workflow_name="agentspec_support_request")
    ],
)

def handle_request(user_id: str, message: str):
    with propagate_attributes(
        customer_identifier=user_id,
        thread_identifier="conv_abc_123",
        metadata={"plan": "pro"},
    ):
        result = langgraph_agent.invoke(
            input={"messages": [{"role": "user", "content": message}]}
        )
        print(result["messages"][-1].content)
```

| Attribute             | Type   | Description                                           |
| --------------------- | ------ | ----------------------------------------------------- |
| `customer_identifier` | `str`  | Identifies the end user in Respan analytics.          |
| `thread_identifier`   | `str`  | Groups related messages into a conversation.          |
| `metadata`            | `dict` | Custom key-value pairs. Merged with default metadata. |