DOCSEARCHbyAlgolia
Submit Docs

AgentScope Studio Documentation

repository·main·Indexed 20 days ago

https://github.com/agentscope-ai/agentscope-studio

A development-oriented visualization toolkit for building, debugging, and evaluating agent-based applications using AgentScope. It provides real-time runtime visualization, OpenTelemetry-based tracing for LLM calls and token usage, statistical evaluation tools, and project management via Projects and Runs. Includes a built-in development assistant, AgentScope-Friday, and supports deployment via Docker and Docker Compose.

Tokens
35K
Snippets
91
Records
136
Agent score
69%

What's inside AgentScope Studio

  2. Overview of AgentScope Studio features

    main

    AgentScope Studio is a local visualization toolkit for AgentScope developers. Key capabilities include:

    • Project Management: Organizing AgentScope projects through Projects and Runs.
    • Runtime Visualization: A chatbot-style interface for real-time interaction with agents.
    • Tracing: OpenTelemetry-based visualization for LLM calls, token usage, and agent invocations.
    • Agent Evaluation: Statistical analysis for evaluating agent performance.
    • Built-in Copilot (Friday): A development assistant and playground for rapid development and feature integration.

  3. AgentScope-Friday features and capabilities

    main

    AgentScope-Friday is an evolving agent with the following feature set:

    Implemented Features:

    • Basic chat functionality with LLMs
    • Meta tool support
    • Realtime steering and interruption (via websocket connection)
    • State and Session management

    Upcoming/In-Progress Features:

    • Planning and plan visualization
    • Long-term memory
    • Anthropic agent skill support
    • Dynamic user addition of MCP (Model Context Protocol) servers

  5. Understand the AgentScope-Studio directory structure

    main

    When adding or modifying files, follow the established directory structure:

    Client (packages/client/src/):

    • assets/: Static resources (images, icons)
    • components/: React UI components
    • context/: React Context providers for state management and data fetching
    • i18n/: Internationalization files
    • pages/: Page components for different routes
    • utils/: Utility functions and helpers

    Server (packages/server/src/):

    • dao/: Data Access Objects for database interaction
    • migrations/: Database migration scripts
    • models/: Database models
    • otel/: OpenTelemetry tracing configuration
    • trpc/: tRPC API route handlers
    • utils/: Utility functions and helpers
    • database.ts: Database connection settings
    • index.ts: Server entry point

  6. Understand AgentScope-Studio observability semantic conventions

    main

    AgentScope-Studio uses observability data that follows the OpenTelemetry semantic conventions. Adhering to these conventions ensures that your trace data is processed and displayed accurately and clearly within the Studio UI.

    Note: The native AgentScope library already follows these conventions. If you provide data from other sources that do not follow these conventions, traces will still be displayed, but critical information may not be highlighted or specifically formatted in the UI.

  7. How Run Visualization and Trace data work

    main

    When viewing a Run in AgentScope-Studio, you can monitor execution through two primary lenses:

    1. Chatbot-style UI: Displays the interaction history. Because a single agent reply can generate multiple messages (e.g., user prompts and system tool results), Studio allows you to toggle the view between replyId (grouping messages into complete agent replies) or msg.id (viewing individual messages).
    2. Trace Visualization: The right panel provides OpenTelemetry-based trace data. This allows you to inspect the detailed inputs and outputs of specific agent objects, LLM calls, and tool usage during the run.

    Studio also supports User Input Hosting, where the Studio interface acts as a bridge, hosting user inputs and pushing them in real-time to your Python agent application via WebSockets.

  8. How Run Visualization and Replies work

    main

    In AgentScope, a single agent reply (one call to the reply function) can generate multiple Msg objects (e.g., 'user' role prompts or 'system' role tool results).

    To make visualization intuitive, AgentScope-Studio introduces the reply concept. A reply groups multiple messages into a single logical unit of an agent's response.

    In the Studio UI, developers can toggle between viewing messages by replyId (grouped by response) or by msg.id (individual messages).

  9. Key features of AgentScope-Studio

    main

    AgentScope-Studio provides several core capabilities for agent development:

    • Project management and chatbot-style visualization: Manage projects and view agent interactions in a chat interface.
    • OpenTelemetry-based tracing visualization: Visualize traces generated via OpenTelemetry to debug agent workflows.
    • Evaluation-oriented analysis and visualization: Tools for analyzing and visualizing the performance and results of agent evaluations.
    • AgentScope-Friday: A built-in agent designed to assist with quick secondary development tasks.

  10. AgentScope-Friday Project Structure

    main

    If you are performing secondary development on the Friday agent, the core logic is organized as follows:

    • main.py: The entry point for the Friday agent.
    • args.py: Parameter parser for the agent.
    • model.py: Handles LLM initialization based on configuration.
    • hook.py: Contains hook functions used to push messages to the AgentScope-Studio frontend.
    • utils/connect.py: Manages the WebSocket connection used for real-time control and interruption.
    • tool/: Directory containing agent tools.
    • requirements.txt: List of dependencies required for the Friday agent.
    packages/
    app/
        friday/
            tool/
            utils/
                connect.py  # 用于实时操控/中断的 websocket 连接
                ...
            main.py         # Friday 智能体的入口点
            args.py         # Friday 智能体的参数解析器
            hook.py         # 用于将消息推送到 AgentScope-Studio 前端的钩子函数
            model.py        # 基于配置初始化 LLM
        requirements.txt    # Friday 智能体的依赖项

  11. How Projects and Runs organize observability data

    main

    AgentScope-Studio uses a two-tier organizational structure to manage AI application data:

    • Projects: High-level containers used to isolate different AI applications or experimental environments.
    • Runs: Individual execution instances within a project. A Run represents a single complete running process or session, tracking its own specific execution history and status.

    By using this hierarchy, you can separate observability data for different experiments and manage multiple execution instances under a single project umbrella.

  12. Configure data persistence for AgentScope Studio

    main

    To ensure user data is preserved across container restarts, you should mount the container's /app/data directory to a host directory. By default, the docker-compose.yml maps the host ./data directory to the container's /app/data directory.

    volumes:
    - ./data:/app/data