---

name: agent-runtime description: "Implement/debug Yuxi agent runtime, APIs, tools, skills, MCP, subagents, queue, streaming, and middleware behavior." metadata: disco-role: operating disable-model-invocation: true license: MIT

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

1. Classify the failing layer. Use references/agent-runtime-map.md to decide whether the change belongs in context/config, request intake and queueing, run execution, stream serialization, middleware, sandbox/files, tools/Skills/MCP, or subagents.
2. 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.
3. 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.
4. 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.context normalization.
• Run submission and queue: start at POST /api/agent/runs, RunSubmissionCommand, and the request queue service for enqueue, reject, and steer semantics.
• Worker execution and streaming: follow AgentRun creation, ARQ enqueue, stream_agent_chat/resume, Redis stream events, and /api/agent/runs/{run_id}/events SSE 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.md for activation, gating, storage, async subagent lifecycle, and sandbox boundaries.
• Known failure modes: use references/troubleshooting.md before 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_skill unit 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.