Agency：用于 AI Agent 调试、性能分析与监控的开源平台

Agency 是由 UC Berkeley Sky Computing Lab 开发的开源平台，专用于 AI Agent 的运行、调试、性能分析（Profiling）与控制。

随着 Agent 承担的任务耗时越来越长、调用的工具越来越复杂以及并行工作的展开，理解它们实际上在做什么变得愈发困难。仅凭大模型的 Trace 只能揭示一部分事实：Agent 究竟在等待什么？时间耗费在了哪里？为什么某次运行会比另一次慢？

Agency 将 LLM 请求、工具调用与系统活动 整合在同一处，为你提供端到端的可视化能力，以排查执行过程、定位瓶颈并洞察发生了哪些变化。

我们支持模型与运行框架无关（Model and Harness Agnostic）！无论是运行 Claude Code、Codex、OpenCode 还是 Agency 的原生 harness，均可适配包括 OpenAI、Anthropic、Bedrock 以及基于 vLLM 的本地模型等主流后端。立即开始使用吧。

Agency 能为你做什么

实时执行（Live Execution）——洞察正在发生的一切

将其视为 面向 AI Agent 的 htop + gdb。

实时观察 Agent 的执行过程。跨多个 Agent 检查模型请求、工具调用、输出结果、失败状态和等待时间。支持直接从 Web 控制面板暂停、恢复或终止兼容的执行任务。

当执行结束时，该视图将自动转化为可供回溯浏览的完整执行历史记录。

关键路径（Critical Path）——找出拖慢速度的瓶颈

直观查看物理墙上时钟时间（Wall-clock Time）究竟花在了哪里。

追踪模型请求、工具调用、底层进程以及跨 Agent 的依赖关系。精准识别决定最终耗时的关键任务，清晰区分并行执行与阻塞等待，并深入排查系统瓶颈。

在执行结束后，使用 Critical Path Profiler 深入分析到底是什么阻碍了运行效率。

深度性能分析（Detailed Profiler）——更进一步的度量

深入挖掘执行背后的底层指标数据。

探究 LLM 延迟、Token 使用量、工具耗时、报错信息、重试次数，以及 CPU、内存、I/O 和可选的 GPU 指标。通过关联记录，实现从高层宏观活动逐级下钻到单个事件与底层进程。

拒绝臆造数据。缺失的度量指标将如实呈现为缺失。

对比运行记录（Compare Runs）——洞悉变化与差异

并排对比已完成的不同运行任务。

全面比对执行轨迹、模型与工具活动、延迟表现、资源占用、失败异常及最终输出。精准定位执行路径从何处发生分歧，以及哪些度量指标发生了波动。

Agency 基于记录的事实证据进行对比，从不主观猜测原因。

赋能你的 Agent 技术栈底层

Agency 提供沙箱执行环境、Python API、受支持的 Agent harnesses 以及集成式遥测功能。你的应用程序依然能全权掌控其工作流编排与逻辑。

层级	支持选项
Agent harnesses	Native, Claude Code, Codex, OpenCode, Grok, Kimi
模型后端	OpenAI Chat Completions / Responses, Anthropic, Amazon Bedrock, OpenAI 兼容端点（包括 vLLM）
运行环境	使用 Docker 或 Podman 的 Linux 沙箱，支持可配置的资源配额与挂载卷

兼容性取决于模型能力、具体配置以及外部 CLI 版本。外部 harness CLI 必须单独安装。

实验性功能： 与 Linux 现有 Claude Code 和 Codex CLI 会话的集成仍处于实验阶段。性能分析、拦截和执行控制功能可能会受限。目前，通过 Python 编排的工作流能提供最完整的体验。

参见 配置与系统要求。

• Linux x86-64 架构与 Python 3.12+
• Git 以及 uv
• Docker 或 Podman
• 已配置模型供应商的 API Key

bash git clone https://github.com/agency-project/agency.git cd agency uv sync --locked --python 3.12

export OPENAI_API_KEY="your-api-key" export OPENAI_MODEL="gpt-6-luna"

uv run python examples/quickstart.py

这将会在一个隔离的沙箱中运行原生 Agent。所配置的模型必须支持 reasoning_effort="none"。模型 API 的调用可能会产生费用。

首次启动需要联网以下载沙箱镜像及相关依赖项。无需 GPU、ZFS 或 CRIU 支持。

bash AGENCY_PROFILE=1 AGENCY_PROFILE_SCOPE=workload
uv run python examples/quickstart.py --webui

在浏览器中打开 localhost:7860 即可查看实时执行界面，访问 localhost:7860/profiler 则可使用性能分析面板。

控制面板默认绑定至 0.0.0.0；在没有设置相应访问权限控制的情况下，请勿直接将其暴露至非受信任的网络环境。

有关 Python 集成方式，请参见 examples/quickstart.py。你可以独立配置 harness 与模型，通过类型化的输入和输出定义任务，并收集执行记录以供后续深入分析。

Agency 完全开源。欢迎提交贡献、问题反馈与改进建议。

请查阅 CONTRIBUTING.md 了解如何开始参与贡献。

Agency is an open-source platform developed at UC Berkeley Sky Computing Lab for running, debugging, profiling, and controlling AI agents.

As agents tackle longer tasks, invoke tools, and work in parallel, understanding what they're actually doing gets harder. Model traces only tell part of the story. What is an agent waiting for? Where is time being spent? Why is one run slower than another?

Agency connects LLM requests, tool calls, and system activity in one place, giving you the visibility to investigate execution, find bottlenecks, and understand what changed.

We are model and harness agnostic! Run Claude Code, Codex, OpenCode, or Agency's native harness with supported backends including OpenAI, Anthropic, Bedrock, and local models via vLLM. Get started

What you can do with Agency

Live Execution — See what's happening

Think htop + gdb for AI agents.

Watch agents execute in real time. Inspect model requests, tool calls, outputs, failures, and waits across agents. Pause, resume, or stop supported executions directly from the dashboard.

When execution finishes, the same view becomes a navigable history of everything that happened.

Critical Path — Find what's slowing you down

See where wall-clock time actually goes.

Trace model requests, tool calls, processes, and dependencies across agents. Identify the work determining completion time, distinguish parallel execution from waiting, and zoom into bottlenecks.

Use the Critical Path Profiler after execution to investigate what held the run back.

Detailed Profiler — Go deeper

Dig into the measurements behind execution.

Explore LLM latency, token usage, tool durations, errors, retries, CPU, memory, I/O, and optional GPU metrics. Follow linked records from high-level activity down to individual events and processes.

No invented numbers. Missing measurements stay missing.

Compare Runs — Understand what changed

Compare completed runs side by side.

Examine execution trajectories, model and tool activity, latency, resource usage, failures, and outcomes. Find where execution paths diverged and which measurements changed.

Agency compares recorded evidence, without guessing at causes.

Underneath your agent stack

Agency provides a sandboxed execution environment, Python API, supported agent harnesses, and integrated telemetry. Your application keeps control of its workflow and orchestration.

Layer	Supported options
Agent harnesses	Native, Claude Code, Codex, OpenCode, Grok, Kimi
Model backends	OpenAI Chat Completions / Responses, Anthropic, Amazon Bedrock, OpenAI-compatible endpoints (including vLLM)
Environment	Linux sandboxes using Docker or Podman, with configurable resources and mounts

Compatibility depends on model capabilities, configuration, and external CLI versions. External harness CLIs must be installed separately.

Experimental: Integration with existing Claude Code and Codex CLI sessions on Linux is experimental. Profiling, interception, and execution controls may be limited. Python-orchestrated workflows currently provide the most complete experience.

See configuration and requirements.

• Linux x86-64 and Python 3.12+

• Git and uv

• Docker or Podman

• API key for your configured model provider

  git clone https://github.com/agency-project/agency.git cd agency uv sync --locked --python 3.12

  export OPENAI_API_KEY="your-api-key" export OPENAI_MODEL="gpt-6-luna"

  uv run python examples/quickstart.py

This runs a native agent in an isolated sandbox. The configured model must support reasoning_effort="none". Model API usage may incur charges.

First startup requires network access for the sandbox image and dependencies. No GPU, ZFS, or CRIU required.

AGENCY_PROFILE=1 AGENCY_PROFILE_SCOPE=workload \
  uv run python examples/quickstart.py --webui

Open localhost:7860 for live execution and localhost:7860/profiler for profiling.

The dashboard binds to 0.0.0.0 by default; don't expose it to untrusted networks without appropriate access controls.

For Python integration, see examples/quickstart.py. You can configure the harness and model independently, define tasks with typed inputs and outputs, and collect execution records for later analysis.

Agency is open source. Contributions, bug reports, and feedback are welcome.

See CONTRIBUTING.md to get started.