AgentScope (tracing) | Respan Docs

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

Set up Respan

Create an account at platform.respan.ai and grab an API key.

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

Use Respan Gateway

See AgentScope gateway setup to route model calls through the Respan gateway.

Example projects

Python examples

Setup

Install packages

$ pip install respan-ai respan-instrumentation-agentscope agentscope openai

Set environment variables

$ 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

1 import asyncio
2 import os
3 
4 from agentscope.agent import Agent
5 from agentscope.credential import OpenAICredential
6 from agentscope.message import UserMsg
7 from agentscope.model import OpenAIChatModel
8 from respan import Respan, workflow
9 from respan_instrumentation_agentscope import AgentScopeInstrumentor
10 
11 credential = OpenAICredential(api_key=os.environ["OPENAI_API_KEY"])
12 model = OpenAIChatModel(
13     credential=credential,
14     model="gpt-4o-mini",
15     stream=False,
16 )
17 
18 respan = Respan(
19     app_name="agentscope-demo",
20     instrumentations=[AgentScopeInstrumentor(model=model)],
21 )
22 
23 agent = Agent(
24     name="PlanningAgent",
25     system_prompt="Return concise planning updates.",
26     model=model,
27 )
28 
29 @workflow(name="agentscope_agent_reply")
30 async def run_agent() -> str:
31     result = await agent.reply(UserMsg(name="user", content="Draft a tiny plan."))
32     return result.get_text_content()
33 
34 async def main() -> None:
35     print(await run_agent())
36 
37 asyncio.run(main())
38 respan.flush()
39 respan.shutdown()

View your trace

Open the Traces page 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.

1 from respan import Respan
2 from respan_instrumentation_agentscope import AgentScopeInstrumentor
3 
4 respan = Respan(
5     instrumentations=[AgentScopeInstrumentor(model=model)],
6     customer_identifier="user_123",
7     metadata={"service": "agentscope-api", "version": "1.0.0"},
8     environment="production",
9 )

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.