Skip to content

chore(doc): rename Studio doc to Observability & Studio with OpenTelemetry tracing guide #1186

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
LearningGp wants to merge 1 commit into
base: main
Choose a base branch
from
+252 −59
Open

chore(doc): rename Studio doc to Observability & Studio with OpenTelemetry tracing guide #1186

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 4 additions & 4 deletions docs/_toc.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -54,8 +54,8 @@ parts:
title: Multimodal
- file: en/task/structured-output
title: Structured Output
- file: en/task/studio
title: Studio
- file: en/task/observability
title: Observability & Studio
- file: en/task/agui
title: AG-UI Protocol
Comment on lines 56 to 60
Copy link

Copilot AI Apr 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The TOC now points to en/task/observability, but there are still docs linking to the removed task/studio.md (e.g., docs/en/intro.md). Please update those links so users don’t hit a 404.

Copilot uses AI. Check for mistakes.
Copy link
Copy Markdown
Collaborator

@chickenlj chickenlj Apr 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@copilot apply changes based on this feedback

- file: en/task/a2a
Expand Down Expand Up @@ -129,8 +129,8 @@ parts:
title: 多模态
- file: zh/task/structured-output
title: 结构化输出
- file: zh/task/studio
title: Studio
- file: zh/task/observability
title: 可观测与调试
- file: zh/task/agui
title: AG-UI 协议
- file: zh/task/a2a
Comment on lines 131 to 136
Copy link

Copilot AI Apr 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

目录已从 zh/task/studio 改为 zh/task/observability，但仍有文档链接指向已移除的 task/studio.md（如 docs/zh/intro.md）。请同步更新这些链接，避免导航到不存在的页面。

Copilot uses AI. Check for mistakes.
Copy link
Copy Markdown
Collaborator

@chickenlj chickenlj Apr 10, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@copilot apply changes based on this feedback

Expand Down
152 changes: 124 additions & 28 deletions docs/en/task/studio.md → docs/en/task/observability.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,10 +1,19 @@
# Studio (Visual Debugging)
# Observability & Studio

AgentScope Java provides multiple mechanisms for observing and debugging agent execution:

- **Studio (Visual Debugging)**: Real-time visualization and interactive debugging through a Web UI
- **OpenTelemetry Tracing**: Export trace data to external observability platforms (e.g., Langfuse, Jaeger) via the OTLP protocol

---

## Studio (Visual Debugging)

Studio provides a Web interface for real-time visualization of Agent execution processes, supporting interactive debugging and message tracing.

---

## Core Features
### Core Features

- **Real-time Visualization**: Web interface displays Agent reasoning and execution processes
- **Interactive Input**: Interact with Agent through Web UI
Expand All @@ -13,9 +22,9 @@ Studio provides a Web interface for real-time visualization of Agent execution p

---

## Quick Start
### Quick Start

### 1. Start Studio Server
#### 1. Start Studio Server

Start from source code
```bash
Expand All @@ -34,7 +43,7 @@ Studio will run at http://localhost:5173
![Studio Server Page](../../imgs/studioServer.png)


### 2. Java Application Integration
#### 2. Java Application Integration

```java
import io.agentscope.core.studio.StudioManager;
Expand Down Expand Up @@ -63,13 +72,13 @@ agent.call(msg).block();
StudioManager.shutdown();
```

### 3. View Trace Information in AgentScope Studio
#### 3. View Trace Information in AgentScope Studio

![Trace Information](../../imgs/studioServer-trace.png)



## StudioUserAgent
### StudioUserAgent

Receive user input through Web UI.

Expand All @@ -90,26 +99,26 @@ You can find the Project in Studio's Projects and debug through the WebUI

![Studio Server Web UI Input Interface](../../imgs/studioServer-webUI.png)

### Conversation Loop
#### Conversation Loop

```java
Msg msg = null;
while (true) {
// Get user input from Web UI
msg = user.call(msg).block();

if (msg == null || "exit".equalsIgnoreCase(msg.getTextContent())) {
break;
}

// Agent processes
msg = agent.call(msg).block();
}
```

---

## Complete Example
### Complete Example

```java
package io.agentscope.examples;
Expand All @@ -122,12 +131,12 @@ import io.agentscope.core.studio.StudioMessageHook;
import io.agentscope.core.studio.StudioUserAgent;

public class StudioExample {

public static void main(String[] args) throws Exception {
String apiKey = System.getenv("DASHSCOPE_API_KEY");

System.out.println("Connecting to Studio at http://localhost:3000...");

// Initialize Studio
StudioManager.init()
.studioUrl("http://localhost:3000")
Expand All @@ -136,7 +145,7 @@ public class StudioExample {
.initialize()
.block();
System.out.println("Connected to Studio\n");

try {
// Create Agent (with Studio Hook)
ReActAgent agent = ReActAgent.builder()
Expand All @@ -148,39 +157,39 @@ public class StudioExample {
.build())
.hook(new StudioMessageHook(StudioManager.getClient()))
.build();

// Create user Agent
StudioUserAgent user = StudioUserAgent.builder()
.name("User")
.studioClient(StudioManager.getClient())
.webSocketClient(StudioManager.getWebSocketClient())
.build();

// Conversation loop
System.out.println("Starting conversation (type 'exit' to quit)");
System.out.println("Open http://localhost:3000 to interact\n");

Msg msg = null;
int turn = 1;
while (true) {
System.out.println("[Turn " + turn + "] Waiting for user input...");
msg = user.call(msg).block();

if (msg == null || "exit".equalsIgnoreCase(msg.getTextContent())) {
System.out.println("\nConversation ended");
break;
}

System.out.println("[Turn " + turn + "] User: " + msg.getTextContent());
msg = agent.call(msg).block();

if (msg != null) {
System.out.println("[Turn " + turn + "] Agent: "
System.out.println("[Turn " + turn + "] Agent: "
+ msg.getTextContent() + "\n");
}
turn++;
}

} finally {
System.out.println("\nShutting down...");
StudioManager.shutdown();
Expand All @@ -192,9 +201,9 @@ public class StudioExample {

---

## Advanced Usage
### Advanced Usage

### Manual Message Pushing
#### Manual Message Pushing

```java
StudioClient client = StudioManager.getClient();
Expand All @@ -208,7 +217,7 @@ client.pushMessage(customMsg).block();
```


### Multi-Agent Visualization
#### Multi-Agent Visualization

```java
// Add Hook to each Agent
Expand All @@ -224,11 +233,98 @@ ReActAgent agent2 = ReActAgent.builder()

// Studio will display messages from both Agents separately
```

---

## OpenTelemetry Tracing

AgentScope Java integrates with OpenTelemetry to provide distributed tracing for agent execution. You can export traces to any platform that supports the OTLP protocol, such as Langfuse.

### Quick Start

Use `TelemetryTracer` and register it via `TracerRegistry` to enable automatic tracing for all agent calls, model calls, and tool executions:

```java
import io.agentscope.core.tracing.TracerRegistry;
import io.agentscope.core.tracing.telemetry.TelemetryTracer;

// Register a TelemetryTracer with an OTLP endpoint
TracerRegistry.register(
TelemetryTracer.builder()
.endpoint("https://your-otlp-endpoint/v1/traces")
.build()
);

// After registration, all agent activities are automatically traced
ReActAgent agent = ReActAgent.builder()
.name("Assistant")
.model(model)
.build();
```

Once registered, the tracer automatically captures:
- **Agent calls** — span for each `agent.call()`
- **Model calls** — span for each LLM invocation
- **Tool executions** — span for each tool call
- **Formatting** — span for message formatting

No additional code is needed — tracing is applied globally.

### Configuration

`TelemetryTracer` supports the following builder options:

| Option | Description | Default |
|----------------|---------------------------------------------------|---------|
| `endpoint` | OTLP endpoint URL | — |
| `addHeader` | Add a single HTTP header (e.g., for auth) | — |
| `headers` | Set all HTTP headers as a `Map` | — |
| `enabled` | Enable or disable tracing | `true` |
| `tracer` | Use a custom OpenTelemetry `Tracer` instance | — |

### Integration with Langfuse

[Langfuse](https://langfuse.com/) is an open-source observability platform that supports the OpenTelemetry protocol. You can send traces to Langfuse Cloud or a self-hosted instance.

```java
import io.agentscope.core.tracing.TracerRegistry;
import io.agentscope.core.tracing.telemetry.TelemetryTracer;
import java.util.Base64;

// Encode your Langfuse API key as Base64
String publicKey = "pk-lf-xxxxxxxx";
String secretKey = "sk-lf-xxxxxxxx";
String encoded = Base64.getEncoder().encodeToString((publicKey + ":" + secretKey).getBytes());

TracerRegistry.register(
TelemetryTracer.builder()
.endpoint("https://cloud.langfuse.com/api/public/otel/v1/traces")
.addHeader("Authorization", "Basic " + encoded)
.addHeader("x-langfuse-ingestion-version", "4")
.build()
);
```

> **Note**: The `x-langfuse-ingestion-version` header is required by Langfuse when using the OTLP endpoint. Make sure to include it.

After running your agent, you can view the traces in the Langfuse dashboard, including the full call chain, latency, and input/output of each step.

### Integration with Other OTLP Backends

Any platform that supports the OTLP protocol can be used. For example, to send traces to a local Jaeger instance:

```java
TracerRegistry.register(
TelemetryTracer.builder()
.endpoint("http://localhost:4317")
.build()
);
```

---

## More Resources

- **Complete Example**: [StudioExample.java](https://github.com/agentscope-ai/agentscope-java/blob/main/agentscope-examples/advanced/src/main/java/io/agentscope/examples/advanced/StudioExample.java)
- **Studio Example**: [StudioExample.java](https://github.com/agentscope-ai/agentscope-java/blob/main/agentscope-examples/advanced/src/main/java/io/agentscope/examples/advanced/StudioExample.java)
- **Studio Repository**: https://github.com/agentscope-ai/agentscope-studio
- **Hook Documentation**: [hook.md](./hook.md)

Loading
Loading