agent-runtime
Implement/debug Yuxi agent runtime, APIs, tools, skills, MCP, subagents, queue, streaming, and middleware behavior.
- License 许可
- MIT
- 最近更新
- 2026-10-08
- Stars
- ★ 11
- Forks
- 3
01 前言 Front Matter
- name
- agent-runtime
- license
- MIT
- metadata
- { "disco-role": "operating" }
- description
- Implement/debug Yuxi agent runtime, APIs, tools, skills, MCP, subagents, queue, streaming, and middleware behavior.
- disable-model-invocation
- true
02 资源文件 3
- 参考文档references/agent-runtime-map.md16.3 KB
- 参考文档references/tools-skills-mcp-subagents.md15.4 KB
- 参考文档references/troubleshooting.md18.9 KB
03 SKILL.md 正文
Yuxi Agent Runtime
Use this sub-skill when the task touches Yuxi's LangGraph/FastAPI agent execution path: agent configuration and context, run submission, request queue and steer behavior, worker/SSE streaming, middleware, attachments, built-in tools, Skills, MCP, subagents, sandbox file boundaries, API-key access, or Langfuse/evaluation runtime hooks.
Do not use it as the primary guide for deployment topology, knowledge-base ingestion internals, OCR engine selection, CLI usage, or general repo development; route those to the sibling sub-skills and use this one only for the agent-facing boundary.
First decisions
- Classify the failing layer. Use
references/agent-runtime-map.mdto decide whether the change belongs in context/config, request intake and queueing, run execution, stream serialization, middleware, sandbox/files, tools/Skills/MCP, or subagents. - Apply safety gates before probing. API keys, provider keys, Langfuse keys, MCP endpoints, remote Skill sources, Tavily, non-local OCR, and live model calls are service/credential gated. Do not print secrets or run side-effectful external calls without explicit approval.
- Prefer CPU-safe unit proofs first. Most runtime contracts are covered by backend unit tests. E2E stream/subagent/personal-Skill checks require a running Docker Compose stack and sometimes admin credentials.
- Keep HTTP routes thin. Route code should validate request/auth/response shape and delegate stateful behavior to services/repositories.
Quick route map
- Agent definition/config: inspect BaseAgent/BaseContext/ChatBotContext/SubAgentContext, Agent repository serialization, and
config_json.contextnormalization. - Run submission and queue: start at
POST /api/agent/runs,RunSubmissionCommand, and the request queue service forenqueue,reject, andsteersemantics. - Worker execution and streaming: follow AgentRun creation, ARQ enqueue,
stream_agent_chat/resume, Redis stream events, and/api/agent/runs/{run_id}/eventsSSE serialization. - Middleware behavior: inspect the built-in Chatbot/SubAgent graph assembly, then the specific middleware in question: filesystem, attachments, Skills, subagent task tools, summary/offload, image-input compatibility, token usage, model retry, or tool approval.
- Tools, Skills, MCP, subagents: use
references/tools-skills-mcp-subagents.mdfor activation, gating, storage, async subagent lifecycle, and sandbox boundaries. - Known failure modes: use
references/troubleshooting.mdbefore making broad changes.
Safe command entry points
Run commands from the repository root. Docker Compose is the canonical development runtime.
# Non-mutating service/log probes
docker compose ps
docker logs api-dev --tail 100
docker logs worker-dev --tail 100
docker logs sandbox-provisioner --tail 100
curl -s http://localhost:5050/api/system/health
curl -s http://localhost:8002/health
# CPU-safe unit coverage for this sub-skill
docker compose exec api uv run --group test pytest \
test/unit/routers/test_skill_router.py \
test/unit/services/test_skill_service.py \
test/unit/backends/test_sandbox_backends.py \
test/unit/services/test_agent_request_queue_service.py \
test/unit/middlewares/test_steer_middleware.py \
test/unit/middlewares/test_subagent_task_middleware.py \
test/unit/services/test_subagent_run_service.py \
test/unit/routers/test_mcp_router.py \
test/unit/services/test_mcp_service.py \
test/unit/toolkits/test_install_skill.py
Only run the E2E candidates when the stack is intentionally running and test credentials are available:
docker compose exec api uv run --group test pytest -m e2e \
test/e2e/test_subagent_stream_e2e.py \
test/e2e/test_personal_skill_agent_e2e.py
Native proof candidates
- Required CPU/any: skill router, skill service, sandbox backend/path rules, request queue/steer service, subagent middleware/service, MCP router/service, and
install_skillunit tests. - Optional service-required: subagent streaming E2E and personal Skill agent E2E. These require Docker Compose services and should not be treated as proof when services, admin user, worker, Redis/Postgres, MinIO, or sandbox-provisioner are unavailable.
- Optional external credentials: API-key/SSE examples, live model provider calls, Langfuse/evaluation, Tavily search, remote MCP, and remote Skill installs.
Reference files
references/agent-runtime-map.md— execution architecture, layer ownership, APIs, middleware, streaming, tests, and backend gates.references/tools-skills-mcp-subagents.md— tool registry, built-in/KB tools, Skill install/activation/storage, MCP integration, subagent lifecycle, and sandbox file semantics.references/troubleshooting.md— targeted symptoms, probes, fixes, safety boundaries, and test selection.
04 同仓库更多 Skills
obsidian-clipper-template-creator
Guide for creating templates for the Obsidian Web Clipper. Use when you want to create a new clipping template, understand available variables, or format clipped content.
obsidian-clipper-template-creator
Guide for creating templates for the Obsidian Web Clipper. Use when you want to create a new clipping template, understand available variables, or format clipped content.
python-api
Programmatic Object-Detection-Metrics API guidance for BoundingBox, BoundingBoxes, Evaluator, enums, coordinate conversion, AP/mAP semantics, and source-style import diagnostics.
file-evaluation
Folder-based PASCAL VOC AP/mAP evaluation from ground-truth and detection text files.
object-detection-metrics
Guides legacy Object-Detection-Metrics PASCAL VOC AP/mAP evaluation from detection text folders and direct Python API classes.
nx-workspace-patterns
Configure and optimize Nx monorepo workspaces. Use when setting up Nx, configuring project boundaries, optimizing build caching, or implementing affected commands.