agenticore (The Cloud Clock Work)

代理

两种模式，一种二进制。 运行一组克隆repos和发布PR的Claude Code代理，或者将任何定制的Claude Codes代理作为实时、兼容OpenAI的聊天完成端点公开 逐令牌思维与工具增量.使用一个环境变量在模式之间切换。

  ](https://hub.docker.com/r/tccw/agenticore)   

                          ┌─── AGENT_MODE=false (default) ────────────┐
                          │  FLEET MODE — Orchestrator                 │
                          │  Submit a task, get a PR                   │
                          │                                            │
   MCP / REST / CLI ─────►│  clone repo ──► bespoke worktree           │
                          │       │              │                     │
                          │       └──► claude -p "" ──► auto-PR  │
                          │                              └──► OTEL     │
                          │  KEDA-scaled fleet • work-stealing queue   │
   ┌─────────────┐        └────────────────────────────────────────────┘
   │ agenticore  │
   │   binary    │
   └─────────────┘        ┌─── AGENT_MODE=true ────────────────────────┐
                          │  AGENT MODE — Customized agent endpoint    │
                          │  Drop-in OpenAI chat completion server     │
                          │                                            │
   OpenAI-compatible ────►│  load agent package (system prompt, MCP    │
   chat clients           │    servers, hooks, skills, identity)       │
   (LibreChat,            │                                            │
    OpenWebUI,            │  POST /v1/chat/completions stream=true     │
    LiteLLM,              │       │                                    │
    custom UI,            │       └─► live SSE deltas:                 │
    raw curl -N)          │            thinking_delta (token-by-token) │
                          │            tool_use + tool_result          │
                          │            assistant text                  │
                          │                                            │
                          │  Sticky slash toggles per agent            │
                          │  Fully auditable — wire/disk/Redis layers  │
                          └────────────────────────────────────────────┘

______________________________________________________________________

选择一种模式

两种模式共享 相同二进制，the 相同的Docker镜像，the 相同的Helm图表，相同的配置文件系统，相同的Redis+文件回退，以及相同的OTEL跟踪管道。 安装时不要选择。您在运行时使用一个环境变量进行选择。

______________________________________________________________________

为什么选择agenticore

你有克劳德密码。您希望它以编程方式为您工作。你的作品往往呈现出两种形态：

1. 跨仓库的无头编码任务 --“修复auth错误”，“为解析器添加测试”，“重构此模块”。你想要一个接受这些的舰队，克隆正确的仓库，在干净的工作树中运行Claude，并打开一个PR。→ 车队模式.

1. 您的其他工具可以与之交谈的定制Claude代理 --个人助理、领域专家、finops机器人、文档编写者——作为OpenAI兼容端点公开，因此LibreChat、OpenWebUI、LiteLLM路由器或任何OpenAI SDK客户端都可以将其作为“模型”放入。随着 实时流媒体 代理的思维、工具调用和答案——没有缓冲、没有批量、没有伪造。 → 代理模式.

Agentcore是一个同时具备这两种功能的二进制文件。配置文件、钩子、MCP白名单、Redis状态、OTEL跟踪、Helm chart——所有这些都在两种模式之间共享。你的运营团队学到了一件事。

______________________________________________________________________

🟦 舰队模式

提交任务，获得PR。原始定位。

MCP Client / REST Client / CLI
            │
            ▼
    ┌── Agenticore (Fleet Mode) ─────────────────────────────────┐
    │   Auth · Router · Job Queue                                │
    │                                                            │
    │   Clone repo ──► Bespoke worktree ──► claude -p "task"     │
    │   (cached)       (locked branch)      (cwd = worktree)     │
    │                                         │                  │
    │                                         ▼                  │
    │                                   Auto-PR (gh)             │
    │                                   Job result → Redis       │
    └──────────────────────┬─────────────────────────────────────┘
                           │
                    OTEL Collector
                    → Langfuse / PostgreSQL

• 接受来自的任务 MCP客户端、REST或CLI -相同的API表面，一个端口
• 克隆和缓存存储库，使用分布式锁序列化并发访问
• 创造 定制工作台 --在Claude启动之前锁定，确定分支名称
• 应用执行配置文件 --安装到 ~/.claude/ 通过agentihooks启动时
• 生成物 claude -p "" 在工作台和 成功后打开PR
• 船舶 完整的OTEL痕迹 （提示、工具调用、令牌计数）发送到Langfuse/PostgreSQL
• KEDA自动缩放 Redis队列深度+ 优雅排水 吊舱关闭

快速入门

# Set credentials
export ANTHROPIC_AUTH_TOKEN=sk-ant-...
export GITHUB_TOKEN=ghp_...

# Start the server
agenticore serve

# Submit a task and wait for the PR URL
agenticore run "fix the null pointer in auth.py" \
  --repo https://github.com/org/repo \
  --wait

表征状态转移

# Submit a job (async — returns immediately with job ID)
curl -X POST http://localhost:8200/jobs \
  -H "Content-Type: application/json" \
  -d '{"task":"fix the auth bug","repo_url":"https://github.com/org/repo"}'

# Submit and wait
curl -X POST http://localhost:8200/jobs \
  -H "Content-Type: application/json" \
  -d '{"task":"fix the auth bug","repo_url":"https://github.com/org/repo","wait":true}'

# Inspect
curl http://localhost:8200/jobs/{job_id}
curl "http://localhost:8200/jobs?limit=10&status=running"
curl -X DELETE http://localhost:8200/jobs/{job_id}

MCP工具（车队模式）

在以下位置连接任何MCP客户端 http://localhost:8200/mcp （流式HTTP）或 /sse （传统苏格兰和南方能源公司）。

______________________________________________________________________

🟩 代理模式

一个环境变量。现在，您有了一个定制的Claude代理，它通过实时思维+工具流来谈论OpenAI协议。

        AGENT_MODE=true + AGENT_MODE_PACKAGE_DIR=./my-agent-package
                                        │
                                        ▼
  ┌── Agenticore (Agent Mode) ──────────────────────────────────────┐
  │                                                                 │
  │   Load package once at startup:                                 │
  │     ├─ system.md (identity, instructions)                       │
  │     ├─ .claude/ (settings, hooks, skills, agents)               │
  │     └─ .mcp.json (tool servers this agent can call)             │
  │                                                                 │
  │   POST /v1/chat/completions stream=true                         │
  │     │                                                           │
  │     ├─ strip slash tokens (server-side, deterministic)          │
  │     ├─ load sticky visibility config from Redis                 │
  │     ├─ spawn claude --output-format stream-json                 │
  │     │                  --include-partial-messages               │
  │     ├─ read claude stdout line-by-line                          │
  │     │     thinking_delta  → delta.reasoning_content (live)      │
  │     │     text_delta      → delta.content (live)                │
  │     │     tool_use_block  → ```tool_use:NAME fenced block       │
  │     │     tool_result     → ```tool_result fenced block         │
  │     └─ flush each chunk to the open HTTP connection             │
  │                                                                 │
  └─────────────────────────────────────────────────────────────────┘

加入任何与OpenAI兼容的客户端。 因为端点会说话 /v1/chat/completions 并发出标准 chat.completion.chunk JSON over SSE，你可以在里面注册一个代理支持的代理作为“OpenAI自定义模型”：

• Librechat --添加为自定义OpenAI端点，从模型下拉列表中选择
• OpenWeb用户界面 --相同的图案
• 轻量级LLM --注册为 openai/ 随着 api_base=http://:8200/v1，然后将任何LiteLLM客户端路由到它
• OpenAI SDK （Python、JS、Go、Rust）-- OpenAI(base_url="http://:8200/v1") 并致电 chat.completions.create(...) 就像你反对的那样 api.openai.com
• curl -N --原始SSE运行良好

杀手级功能

• 实时SSE流媒体，完全可审计，完全可追溯。 思维阻碍了流 逐个令牌 当模型生成它们时。工具调用和结果流 生活 当代理调用它们时。辅助文本流逐步进行。转弯结束时没有缓冲。流式热路径直接通过以下方式读取claude的stdout --output-format stream-json --verbose --include-partial-messages --没有转录轮询，没有Redis间接，没有JSONL刷新竞争。
• 思维呈现在 delta.reasoning_content --推理感知客户端（LibreChat、OpenWebUI）中的独立推理面板，具有 x_agenticore_event_type="thinking" 对于需要显式标记的自定义客户端。
• 工具调用呈现为围栏标记块 — ``` `tool_use:NAME `` 搭配 `` `tool_result `` 在它下面。故意 **不** OpenAI的 delta.tool_calls` 模式，这将使聊天客户端尝试客户端执行该工具，但以“找不到工具”失败。
• 每个代理的粘性可见性切换 在claude看到提示之前，服务器端被拦截：

- /show-thinking / /hide-thinking - /show-tools / /hide-tools - /show-all / /hide-all - /stream-status （将当前配置作为元SSE事件内联返回）

• 多转弯感知 --切换检测与 最后一条用户消息，而不是平坦的历史记录，因此斜线命令在第2+回合有效。 仅切换请求 （例如，只是 /show-all)返回内联状态而不产生claude——零令牌成本。
• 三层观察 --每个可见事件都会到达（1）有线客户端，（2）磁盘上的claude转录JSONL，以及（3）可选的跨进程订阅者的Redis总线（非流式路径）。用以下代码交叉验证所有三个 tests/smoke/verify_streaming_pipeline.sh .
• 异步完成队列 即发即弃- wait=false 推送到Redis，一个工人拿起它，轮询 GET /completions/{uuid}.
• 会话连续性 --通过外部关联UUID跨请求恢复对话。
• Redis+文件回退 --无需Redis即可工作（内联执行，基于文件的状态）。

快速入门

# Start the server in agent mode pointing at your agent package
AGENT_MODE=true \
AGENT_MODE_PACKAGE_DIR=./my-agent-package \
AGENTICORE_TRANSPORT=sse \
agenticore serve

# Toggle visibility once (sticky per agent — persists in Redis)
curl -sN http://localhost:8200/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{"model":"sonnet","stream":true,"messages":[{"role":"user","content":"/show-all"}]}'

# Now have a real conversation — watch thinking tokens + tool calls stream live
curl -sN http://localhost:8200/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{"model":"sonnet","stream":true,"messages":[
        {"role":"user","content":"is 17077 prime? think hard, then list any files in /tmp"}
      ]}'

# Non-streaming JSON (no slash tokens needed)
curl -X POST http://localhost:8200/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{"model":"sonnet","messages":[{"role":"user","content":"hello"}]}'

进入LibreChat

# librechat.yaml
endpoints:
  custom:
    - name: "Agenticore Agents"
      apiKey: "${LITELLM_API_KEY}"
      baseURL: "http://litellm.your-cluster.svc:4000/v1"
      models:
        fetch: true
      titleConvo: true

在LiteLLM中将代理注册为指向agenticore pod的模型：

# Via LiteLLM admin (or the litellm_tools MCP)
model_name: my-agent
litellm_params:
  model: openai/my-agent
  api_base: http://my-agent.namespace.svc:8200/v1

现在 my-agent 显示在LibreChat的模型选择器中。推理面板中呈现逐个标记的思维。工具将流实时调用为围栏标记块。

进入OpenAI SDK

from openai import OpenAI

client = OpenAI(base_url="http://my-agent.namespace.svc:8200/v1", api_key="n/a")

stream = client.chat.completions.create(
    model="sonnet",
    stream=True,
    messages=[
        {"role": "user", "content": "/show-all explain how an OS scheduler works step by step"},
    ],
)
for chunk in stream:
    delta = chunk.choices[0].delta
    if reasoning := getattr(delta, "reasoning_content", None) or delta.model_dump().get("reasoning_content"):
        print(f"[think] {reasoning}", end="", flush=True)
    elif delta.content:
        print(delta.content, end="", flush=True)

完整参考： SSE流媒体文档 · 自检演练 · 代理模式架构

______________________________________________________________________

共享基础设施（两种模式）

以下内容均适用于 两者 车队模式和代理模式。相同的Docker镜像，相同的Helm图，相同的env变量，相同的Redis架构。

安装

pip install agenticore

或来源：

git clone https://github.com/The-Cloud-Clockwork/agenticore.git
cd agenticore
pip install -e .

档案

个人资料包括 目录包 配置Claude Code的运行方式。每个配置文件都是自包含的 .claude/ 树安装到 ~/.claude/ 在容器启动时 agentihooks global.Claude代码读自 ~/.claude/ 默认情况下。

/{name}/
├── profile.yml          ← Agenticore metadata (model, turns, auto_pr, timeout…)
├── .claude/
│   ├── settings.json    ← Hooks, tool permissions, env vars
│   ├── CLAUDE.md        ← System instructions for Claude
│   ├── agents/          ← Custom subagents
│   └── skills/          ← Custom slash-command skills
└── .mcp.json            ← MCP server config merged into the job

配置文件支持通过以下方式继承 extends: 和船一起 agentihooks PyPI包（agenticore的pip依赖项）。个人覆盖住 ~/.agenticore/profiles/；set AGENTICORE_AGENTIHOOKS_URL 克隆fork（或绑定挂载您的本地签出） /agentihooks)对于可编辑的安装dev loopback。完整参考： 配置文件系统文档.

Helm（Kubernetes）

向GHCR发布生产就绪的Helm chart。部署a StatefulSet 带着一个 共享RWX PVC （NFS/EFS/AAzure Files\\Ceph），因此所有Pod共享相同的仓库缓存和作业状态 KEDA自动缩放 Redis队列深度和 优雅排水 在吊舱关闭时。

Internet ──► LoadBalancer :8200
                    │
     ┌──────────────▼──────────────────────────┐
     │  Agenticore StatefulSet (0..N pods)     │
     │  Work-stealing from Redis queue         │
     └──────────┬──────────────────────────────┘
                │                │
         ┌──────▼───────┐  ┌─────▼───────────┐
         │  Redis       │  │  Shared RWX PVC │
         │  jobs · locks│  │  /shared/       │
         │  KEDA queue  │  │  ├─ repos/      │
         └──────────────┘  │  ├─ jobs/       │
                           │  └─ job-state/  │
         KEDA ScaledObject └─────────────────┘
         watches Redis queue

# Create the secret
kubectl create secret generic agenticore-secrets \
  --from-literal=redis-url="redis://:password@redis:6379" \
  --from-literal=anthropic-api-key="sk-ant-..." \
  --from-literal=github-token="ghp_..."

# Install (fleet mode)
helm install agenticore \
  oci://ghcr.io/the-cloud-clockwork/charts/agenticore \
  --set storage.className=your-rwx-storage-class

# Install (agent mode)
helm install my-agent \
  oci://ghcr.io/the-cloud-clockwork/charts/agenticore \
  --set storage.className=your-rwx-storage-class \
  --set agentMode.enabled=true \
  --set agentMode.agentName=my-agent

完整的Kubernetes指南： Kubernetes部署.

码头工人

# Local dev — full stack (Agenticore + Redis + PostgreSQL + OTEL Collector)
cp .env.example .env
docker compose up --build -d

# Production (fleet mode) — Agenticore only
docker run -d -p 8200:8200 \
  -e AGENTICORE_TRANSPORT=sse \
  -e ANTHROPIC_AUTH_TOKEN=sk-ant-... \
  -e REDIS_URL=redis://your-redis:6379/0 \
  -e GITHUB_TOKEN=ghp_... \
  ghcr.io/the-cloud-clockwork/agenticore

# Production (agent mode)
docker run -d -p 8200:8200 \
  -e AGENT_MODE=true \
  -e AGENTIHUB_AGENT=my-agent \
  -e AGENTICORE_TRANSPORT=sse \
  -e ANTHROPIC_AUTH_TOKEN=sk-ant-... \
  -e REDIS_URL=redis://your-redis:6379/0 \
  ghcr.io/the-cloud-clockwork/agenticore

认证

身份验证是 可选的。禁用时，所有端点都是公共的。

# API keys — comma-separated for multiple
AGENTICORE_API_KEYS="key-1,key-2" agenticore serve

通过传递密钥 X-Api-Key 头球 ?api_key=... 查询参数，或 Authorization: Bearer ...The /health 端点始终是公共的。

Claude凭据按顺序解析： CLAUDE_CODE_OAUTH_TOKEN → ANTHROPIC_AUTH_TOKEN + ANTHROPIC_BASE_URLGitHub凭据：GitHub应用程序(GITHUB_APP_ID +密钥+安装ID）→ 静态 GITHUB_TOKEN → 无（仅限公共repos）。

旅馆观察

每个作业（车队模式）和每个完成（代理模式）都会生成一个Langfuse跟踪，其中包含每个克劳德回合的跨度，包括提示、工具调用和令牌计数。

LANGFUSE_PUBLIC_KEY=pk-lf-...
LANGFUSE_SECRET_KEY=sk-lf-...
LANGFUSE_HOST=https://cloud.langfuse.com
AGENTICORE_OTEL_ENABLED=true
OTEL_EXPORTER_OTLP_ENDPOINT=http://otel-collector:4317

捆绑 docker-compose.yml 包括一个预先连接的OTEL收集器，用于将跟踪推送到Langfuse和PostgreSQL。完整设置： OTEL管道文件.

关键环境变量

完整参考： 配置文档.

CLI命令

完整CLI参考： CLI命令.

______________________________________________________________________

文档

开始

• 快速入门
• 连接客户
• SSE流媒体自检

建筑

• 配置文件系统
• 代理模式
• 内部机制
• 作业执行

部署

• Kubernetes
• OTEL管道

参考

• SSE流媒体 --完整块模式、斜线标记、故障模式诊断
• API 参考
• CLI参考
• 配置

______________________________________________________________________

发展

pip install -e ".[dev]"

# Tests
pytest tests/unit -v -m unit --cov=agenticore

# Lint
ruff check agenticore/ tests/
ruff format --check agenticore/ tests/

agentihooks开发环回

agentihooks 船舶作为agenticore的PyPI依赖(agentihooks>=1.8.0 在 pyproject.toml)当你 pip install agenticore 或者构建Docker镜像。你做 不 需要克隆它才能正常工作 运行时。pod重启是升级路径——没有定期的重新同步观察程序。

当你迭代代理书本身时，设置 AGENTICORE_AGENTIHOOKS_URL 并让运行时克隆（或绑定）在同一目标上挂载签出 跳过克隆）。不管怎样， uv pip install -e 与决心背道而驰 因此，对源代码的编辑将在下一次Python导入时生效。

docker-compose.dev.yml 通过绑定挂载本地来连接环回 在URL导出的目标处签出：

volumes:
  - /home/iamroot/dev/agentihooks:/shared/agentihooks
environment:
  AGENTICORE_SHARED_FS_ROOT: /shared
  AGENTICORE_AGENTIHOOKS_URL: https://github.com/your-org/agentihooks

编辑已装载的结账→ 重新运行服务器（或让Python重新导入 工人重新启动）。所有克隆人+观察者机器都消失了；捆绑和代理 通过按需刷新 agenticore hooks sync, POST /admin/sync，或吊舱 重新启动。看 docs/reference/configuration.md 了解完整的env-var语义。

PR欢迎。这 feat/* 回购中的分支显示了最近的工作——最新的功能是逐个令牌的SSE流层(feat/stream-json-direct → dev → main 在 f440e3c，发布为 v1.3.0).