> ## Documentation Index
> Fetch the complete documentation index at: https://braintrust.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# AgentScope

> Trace AgentScope multi-agent runs in Braintrust to debug agents, pipelines, and tool calls

If you are a coding agent, prefer the Braintrust [`bt` CLI](/reference/cli/quickstart) for repeatable, scriptable work: running evals, instrumenting code, querying logs, syncing data, managing functions, and configuring coding agents. Use the MCP server for reasoning over Braintrust data in conversation, such as ad-hoc lookups and exploration from your IDE.

[AgentScope](https://github.com/modelscope/agentscope) is a framework for building multi-agent systems. Braintrust traces an AgentScope run as a single nested trace, covering agent replies, sequential and fanout pipelines, tool calls, and model requests.

<Note>Braintrust supports AgentScope 1.x and 2.x, and requires AgentScope v1.0.0 or later. AgentScope 2.x requires Python 3.11 or later.</Note>

<View title="Python" icon="https://img.logo.dev/python.org?token=pk_BdcHD9e5SCW3j1rnJkNyMQ">
  <h2 id="setup-python">
    Setup
  </h2>

  Install the Braintrust SDK and AgentScope, then set your API keys. The examples below use OpenAI.

  <Steps>
    <Step title="Install packages">
      <CodeGroup>
        ```bash uv theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
        uv add braintrust agentscope
        ```

        ```bash pip theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
        pip install braintrust agentscope
        ```
      </CodeGroup>
    </Step>

    <Step title="Set environment variables">
      ```bash title=".env" theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
      BRAINTRUST_API_KEY=<your-braintrust-api-key>
      OPENAI_API_KEY=<your-openai-api-key>
      ```
    </Step>
  </Steps>

  <h2 id="auto-instrumentation-python">
    Auto-instrumentation
  </h2>

  To trace AgentScope alongside Braintrust's other supported libraries, call `braintrust.auto_instrument()` before importing AgentScope. Because AgentScope uses `from agentscope... import` style imports, the call must come first so the patches are in place.

  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    import asyncio

    import braintrust

    braintrust.auto_instrument()
    braintrust.init_logger(project="agentscope-example")  # Replace with your project name

    from agentscope.agent import ReActAgent
    from agentscope.formatter import OpenAIChatFormatter
    from agentscope.memory import InMemoryMemory
    from agentscope.message import Msg
    from agentscope.model import OpenAIChatModel
    from agentscope.tool import Toolkit


    async def main() -> None:
        agent = ReActAgent(
            name="Friday",
            sys_prompt="You are a concise assistant. Answer in one sentence.",
            model=OpenAIChatModel(model_name="gpt-4o-mini", stream=False),
            formatter=OpenAIChatFormatter(),
            toolkit=Toolkit(),
            memory=InMemoryMemory(),
        )
        response = await agent(Msg(name="user", content="Say hello in exactly two words.", role="user"))
        print(response.content if response is not None else "(no response)")


    if __name__ == "__main__":
        asyncio.run(main())
    ```
  </CodeGroup>

  To trace AgentScope without auto-instrumenting other libraries, use `setup_agentscope()` instead of `braintrust.auto_instrument()`. It initializes a Braintrust logger when one isn't already active.

  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark-dimmed"}}
    from braintrust.integrations.agentscope import setup_agentscope

    setup_agentscope(project_name="agentscope-example")

    from agentscope.agent import ReActAgent
    from agentscope.formatter import OpenAIChatFormatter
    from agentscope.memory import InMemoryMemory
    from agentscope.message import Msg
    from agentscope.model import OpenAIChatModel
    from agentscope.tool import Toolkit
    ```
  </CodeGroup>

  <h2 id="what-traced-python">
    What Braintrust traces
  </h2>

  Braintrust traces AgentScope runs as nested spans that mirror the actual execution flow. Captured spans:

  * Agent run spans (`<agent>.reply`, such as `Friday.reply`), with the call input, agent class, and response. Both the 1.x `AgentBase.__call__` and 2.x `Agent.reply` paths are instrumented.
  * Pipeline spans (`sequential_pipeline.run` and `fanout_pipeline.run`), with the names of the participating agents. Child agent, tool, and model spans nest underneath.
  * Tool execution spans (`<tool>.execute`, such as `execute_python_code.execute`), with the tool call, toolkit class, and output, including streamed tool output.
  * Model call spans (`<provider>.call`, such as `OpenAIChat.call`), with messages, tools, and model metadata (model name, provider, and request parameters); response content and token usage (prompt, completion, and total) on completion.
  * Streaming model responses and tool outputs, aggregated into the final span output, with token metrics on model spans.
  * Errors on failed agent runs, pipelines, tool calls, and model calls.

  The integration instruments AgentScope's built-in OpenAI, DashScope, Anthropic, Ollama, Gemini, and Trinity chat models.

  <h2 id="resources-python">
    Resources
  </h2>

  * [AgentScope GitHub repository](https://github.com/modelscope/agentscope)
  * [Braintrust Python SDK reference](/sdks/python/versions/latest)
  * [Trace LLM calls](/instrument/trace-llm-calls)
</View>