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

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

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.