AgentScope

Overview

AgentScope is a Python framework (Apache-2.0) for building agents on a reasoning-acting (ReAct) loop. Version 2.x (2.0.9 at the time of writing) is a rewrite of the 1.x line: the 1.x names (agentscope.init, ReActAgent, DialogAgent, msghub) are gone, and docs for the two majors must not be mixed. Check the installed version with pip show agentscope and read the matching docs at https://docs.agentscope.io/stable/en/index.

Observability is built in through middleware. TracingMiddleware emits OpenTelemetry spans for each reply, model call and tool execution, so traces flow to any OTLP backend (Jaeger, Grafana Tempo, Langfuse, Datadog). AgentScope does not ship its own trace store, decision logger, audit-trail class or replay tool; use your OTLP backend, the streamed events, and persisted agent state for those jobs.

Requires Python 3.11 or newer. There is no Node.js package.

Instructions

Install

pip install agentscope
# 2.0.9 already installs the OpenTelemetry SDK and OTLP exporters; pin them yourself if you depend on them
pip install opentelemetry-sdk opentelemetry-exporter-otlp-proto-http
# Redis state storage and the agent service need extras
pip install "agentscope[storage-redis,service]"

A minimal agent

An agent needs a name, system prompt and a chat model. Credentials are objects built from environment variables, never literals.

import asyncio, os
from agentscope.agent import Agent
from agentscope.credential import AnthropicCredential
from agentscope.message import UserMsg
from agentscope.model import AnthropicChatModel
from agentscope.tool import FunctionTool, Toolkit

def get_order_status(order_id: str) -> str:
    """Look up the shipping status of an order.

    Args:
        order_id: The order number, for example A-10482.
    """
    return f"Order {order_id} shipped on 2026-09-30 and arrives Monday."

agent = Agent(
    name="support-agent",
    system_prompt="You answer order questions. Use the tool for any order lookup.",
    model=AnthropicChatModel(
        credential=AnthropicCredential(api_key=os.environ["ANTHROPIC_API_KEY"]),
        model="claude-sonnet-4-5",
    ),
    toolkit=Toolkit(tools=[FunctionTool(get_order_status)]),
)

async def main():
    reply = await agent.reply(UserMsg(name="user", content="Where is order A-10482?"))
    print(reply.get_text_content())
    print(reply.finished_reason, reply.usage)

asyncio.run(main())

reply() returns one Msg. Check finished_reason (completed, interrupted, exceed_max_iters, error; None means the reply paused for human confirmation) and usage (total input/output tokens). Use agent.reply_stream(msg) to receive events as they are produced, and structured_schema=<Pydantic class> to force a validated result in reply.structured_output.

Other providers use the same shape: OpenAIChatModel, GeminiChatModel, DashScopeChatModel, OllamaChatModel, each with a matching *Credential from agentscope.credential.

Trace with OpenTelemetry

Register a tracer provider once per process, then add the middleware to every agent you want traced.

from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
from agentscope.middleware import TracingMiddleware

provider = TracerProvider()
provider.add_span_processor(
    BatchSpanProcessor(OTLPSpanExporter(endpoint="http://localhost:4318/v1/traces"))
)
trace.set_tracer_provider(provider)

agent = Agent(..., middlewares=[TracingMiddleware()])

Spans are nested: the reply span (agent name, session ID, input and output messages) contains model-call spans (model, provider, token counts, messages) and tool spans (tool name, call ID, arguments, result). Without a registered provider the middleware does nothing and costs almost nothing. For custom spans, use trace.get_tracer("agentscope", agentscope.__version__) and the standard OTel API.

To see spans locally without a collector, swap in ConsoleSpanExporter from opentelemetry.sdk.trace.export.

Cap cost per reply

from agentscope.middleware import ReplyBudgetControlMiddleware

middlewares=[TracingMiddleware(),
             ReplyBudgetControlMiddleware(token_budget=20000, output_token_weight=3.0)]

Once the weighted token cost reaches the budget, the agent is told to wrap up and tools are disabled for the next step.

Leader and members

TeamPipeline (experimental) lets a leader agent assign tasks to member agents through an internal TeamAssign tool. The leader sees only each member's final reply.

from agentscope.pipeline import TeamMember, TeamPipeline

pipe = TeamPipeline(
    leader=leader,                      # Agent with a Toolkit()
    members=[
        TeamMember(agent=researcher, description="Finds and summarizes sources."),
        TeamMember(agent=writer, description="Drafts the report from findings."),
    ],
)

Member names must be unique and differ from the leader's. Tasks for different members run concurrently. launch_console(pipe) from agentscope.console runs it in the terminal.

Persist and resume

agent.state (an AgentState) serializes to JSON: context, permissions, tool state and the position of a paused reply. Pass state= when constructing an agent to resume. agentscope.app.storage.RedisStorage stores it under (user_id, agent_id, session_id); use upsert_session on the first turn, because update_session_state raises KeyError for a session that does not exist yet. Saved states are your audit trail of what the agent saw and did.

Examples

Example 1: Trace a support agent into a local Jaeger

Request: "Add tracing to my support agent so I can see each model and tool call in Jaeger."

Start Jaeger with OTLP enabled (docker run --rm -p 16686:16686 -p 4318:4318 jaegertracing/all-in-one), use the exporter at http://localhost:4318/v1/traces from the section above, add middlewares=[TracingMiddleware()], run the agent, and open http://localhost:16686. Choose the service name you set (TracerProvider(resource=Resource.create({"service.name": "support-agent"})), Resource from opentelemetry.sdk.resources) and you will see one trace per reply with child spans for each model call and get_order_status execution, including token counts.

Example 2: Researcher and writer team with a spend limit

Request: "I want a leader that sends research to one agent and drafting to another, and never spends more than about 20k tokens per reply."

Build researcher and writer as ordinary Agent instances with ReplyBudgetControlMiddleware(token_budget=20000) each, build a leader = Agent(..., toolkit=Toolkit()), wrap them in TeamPipeline as above, and call launch_console(pipe). The leader's trace shows TeamAssign calls; each member's own spans carry their token use. A reply that hits its budget finishes with a short wrap-up instead of more tool calls.

Guidelines

• Do not copy AgentScope 1.x snippets. Search results and older tutorials show agentscope.init(...), ReActAgent, msghub; none apply to 2.x.
• Everything is async: await agent.reply(...) inside asyncio.run.
• Check finished_reason in production code: exceed_max_iters and error replies still return a Msg.
• Traces contain full prompts and tool arguments. Do not send them to a shared collector if they hold personal data, and keep API keys in environment variables, never in prompts.
• TeamPipeline, SOP and realtime features are marked experimental; their interfaces can change between 2.0.x releases. Pin the version.
• Tools that run shell commands (Bash, Write, Edit) are powerful; keep AgentScope's permission mode and a sandboxed workspace (Docker or similar) for untrusted tasks.
• Not the right tool when you need a hosted tracing UI with evaluations out of the box; pair it with an OTLP backend that has one.