AgentSpec (tracing) | Respan Docs

Open Agent Specification (Agent Spec) (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 and grab an API key.

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

Use Respan Gateway

See AgentSpec gateway setup to route this integration through the Respan gateway.

Example projects

Example projects root

Setup

Install packages

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

Set environment variables

$ 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

1 from pyagentspec.adapters.langgraph import AgentSpecLoader
2 from pyagentspec.agent import Agent
3 from pyagentspec.llms import OpenAiConfig
4 from respan import Respan
5 from respan_instrumentation_agentspec import AgentSpecInstrumentor
6 
7 respan = Respan(
8     app_name="agentspec-haiku-agent",
9     instrumentations=[
10         AgentSpecInstrumentor(workflow_name="agentspec_haiku_agent")
11     ],
12 )
13 
14 try:
15     agent = Agent(
16         name="haiku_assistant",
17         description="A helpful assistant that writes haikus.",
18         llm_config=OpenAiConfig(name="openai", model_id="gpt-4.1-nano"),
19         system_prompt="You are a helpful assistant. Respond only with a haiku.",
20     )
21 
22     langgraph_agent = AgentSpecLoader().load_component(agent)
23 
24     result = langgraph_agent.invoke(
25         input={"messages": [{"role": "user", "content": "Write a haiku about recursion."}]}
26     )
27     print(result["messages"][-1].content)
28 finally:
29     respan.shutdown()
30     respan.flush()

View your trace

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

1 from respan import Respan
2 from respan_instrumentation_agentspec import AgentSpecInstrumentor
3 
4 respan = Respan(
5     instrumentations=[
6         AgentSpecInstrumentor(workflow_name="agentspec_support_request")
7     ],
8     customer_identifier="user_123",
9     metadata={"service": "agentspec-api", "version": "1.0.0"},
10 )

With propagate_attributes

Override per-request using a context scope.

1 from respan import Respan, propagate_attributes
2 from respan_instrumentation_agentspec import AgentSpecInstrumentor
3 
4 respan = Respan(
5     instrumentations=[
6         AgentSpecInstrumentor(workflow_name="agentspec_support_request")
7     ],
8 )
9 
10 def handle_request(user_id: str, message: str):
11     with propagate_attributes(
12         customer_identifier=user_id,
13         thread_identifier="conv_abc_123",
14         metadata={"plan": "pro"},
15     ):
16         result = langgraph_agent.invoke(
17             input={"messages": [{"role": "user", "content": message}]}
18         )
19         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.