> 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.

# AgentScope (tracing)

> Trace AgentScope agents, model calls, tool executions, streaming output, and failures with Respan.

[AgentScope](https://docs.agentscope.io/) is a Python framework for building agent applications with model abstractions, messages, and toolkits. Respan patches AgentScope agent, chat model, and toolkit surfaces so agent replies, model calls, tool calls, streaming output, and failures appear as Respan traces.

This tracing setup uses your model provider credentials directly. To route model calls through Respan instead, use the [AgentScope gateway setup](/docs/integrations/gateway/agent-scope).

#### 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 [AgentScope gateway setup](/docs/integrations/gateway/agent-scope) to route model calls through the Respan gateway.

#### Example projects

* [Python examples](https://github.com/respanai/respan-example-projects/tree/main/python/tracing/agentscope)

## Setup

#### Install packages

```bash
pip install respan-ai respan-instrumentation-agentscope agentscope openai
```

#### 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 by AgentScope for direct model requests. `RESPAN_API_KEY` exports traces to Respan.

#### Initialize and run

```python
import asyncio
import os

from agentscope.agent import Agent
from agentscope.credential import OpenAICredential
from agentscope.message import UserMsg
from agentscope.model import OpenAIChatModel
from respan import Respan, workflow
from respan_instrumentation_agentscope import AgentScopeInstrumentor

credential = OpenAICredential(api_key=os.environ["OPENAI_API_KEY"])
model = OpenAIChatModel(
    credential=credential,
    model="gpt-4o-mini",
    stream=False,
)

respan = Respan(
    app_name="agentscope-demo",
    instrumentations=[AgentScopeInstrumentor(model=model)],
)

agent = Agent(
    name="PlanningAgent",
    system_prompt="Return concise planning updates.",
    model=model,
)

@workflow(name="agentscope_agent_reply")
async def run_agent() -> str:
    result = await agent.reply(UserMsg(name="user", content="Draft a tiny plan."))
    return result.get_text_content()

async def main() -> None:
    print(await run_agent())

asyncio.run(main())
respan.flush()
respan.shutdown()
```

#### View your trace

Open the [Traces page](https://platform.respan.ai/platform/traces) to see agent, model, and tool spans in the same trace tree.

## Configuration

| Parameter             | Type           | Default           | Description                                                                 |
| --------------------- | -------------- | ----------------- | --------------------------------------------------------------------------- |
| `api_key`             | `str \| None`  | `RESPAN_API_KEY`  | Respan API key used to export traces.                                       |
| `base_url`            | `str \| None`  | `RESPAN_BASE_URL` | Optional Respan trace export API URL.                                       |
| `instrumentations`    | `list`         | `[]`              | Include `AgentScopeInstrumentor()` or targeted model/toolkit instrumentors. |
| `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, for example `"production"`.                                |

## What gets traced

| AgentScope operation               | Respan span | Notes                                                                                                    |
| ---------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------- |
| `Agent.reply()` / `reply_stream()` | `agent`     | Captures agent name, input, final output, and streaming output after consumption.                        |
| Chat model calls                   | `chat`      | Captures messages, completion, model name, tool definitions, tool calls, and token usage when available. |
| Toolkit `call_tool()`              | `tool`      | Captures tool name, arguments, result, and failures.                                                     |

## Attributes

Set defaults at initialization. These apply to every span emitted by the AgentScope instrumentor.

```python
from respan import Respan
from respan_instrumentation_agentscope import AgentScopeInstrumentor

respan = Respan(
    instrumentations=[AgentScopeInstrumentor(model=model)],
    customer_identifier="user_123",
    metadata={"service": "agentscope-api", "version": "1.0.0"},
    environment="production",
)
```

Use targeted `AgentScopeInstrumentor(model=model)` instances for custom or externally defined AgentScope-compatible models that are not reachable through the default AgentScope module patching path.