菜单
Router for any non-trivial echo-sdk task. Maps user intent to the right module skill and diagram. Invoke FIRST for any change to src/echo/ before reaching for a specific module skill.
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
| name | echo-sdk-overview |
| description | Router for any non-trivial echo-sdk task. Maps user intent to the right module skill and diagram. Invoke FIRST for any change to src/echo/ before reaching for a specific module skill. |
Echo is a framework-agnostic Python SDK for LLM agents. Multi-provider, async-first, Pydantic v2. Each submodule has a tight responsibility — pick the right one before editing.
| Module | Public entry point | Skill | Diagram |
|---|---|---|---|
agents/ | from echo.agents import BaseAgent, GenericAgent, Skill, AgentConfig | echo-sdk/agents | agent-skill-lifecycle.md |
llm/ | from echo.llm import get_llm, LLMConfig, LLMResponse, StreamEvent | echo-sdk/llm | llm-invoke-flow.md |
tools/ | import per subpackage: from echo.tools.core import BaseTool, ElicitationResponse; from echo.tools.mcp import MCPTool, MCPConnectionManager; from echo.tools.elicitation import BaseElicitationTool (see layout note) | echo-sdk/tools | tools-mcp-connection.md |
models/ | from echo.models import ConversationContext, Message, ToolCall, ToolResult | echo-sdk/models | conversation-context-er.md |
prompts/ | from echo.prompts import get_prompt_provider, FetchedPrompt | echo-sdk/prompts | — |
evals/ | from echo.evals import get_eval_provider | echo-sdk/evals | — |
audio/ | from echo.audio import get_transcriber, AudioInput | echo-sdk/audio | — |
databases/ | from echo.databases.postgres import PgQueryTool, PostgresClient | echo-sdk/databases | — |
utils/ | helpers; minimal | — | — |
For the big picture: .claude/diagrams/architecture-overview.md and .claude/diagrams/data-flow-end-to-end.md.
tools/ holds the tool framework only, organized into a foundation + categories:
core/ — the foundation: BaseTool (universal contract) + shared schemas
(directive/result types, elicitation payloads, ToolOutput). Dependency root;
imports nothing else from echo.elicitation/ — BaseElicitationTool category (PAUSE/VISIBLE fixed).mcp/ — MCPTool, MCPConnectionManager, and MCP-private schemas
(MCPServerConfig, errors, transport). Pulls optional mcp/httpx.system/ — SystemTool (echo-internal, __init_subclass__-guarded, not re-exported).Concrete domain tools live with their domain and import the framework:
LoadSkillTool/UnloadSkillTool → echo.skills; PgQueryTool → echo.databases.postgres.
Import policy (tools/): each subpackage owns and exposes its own public API;
the top-level tools/__init__ does NOT re-aggregate them — import from the owning
subpackage (echo.tools.core, .mcp, .elicitation, .system). The sole top-level
convenience re-export is BaseTool. This keeps import echo.tools lean and avoids
dragging the optional mcp/httpx deps. Schemas follow the lowest-common-ancestor
rule: cross-category types live in core, category-private types in their category
(mcp/schemas.py). tools/__init__ never imports skills/databases — graph stays acyclic.
| Task | Route to |
|---|---|
| Add a new LLM provider | echo-sdk/adding-a-provider → then echo-sdk/llm |
| Add a new transcriber / eval / prompt provider | echo-sdk/adding-a-provider → then module skill |
| Build a new agent | echo-sdk/agents |
| Attach a skill to an agent | echo-sdk/adding-a-skill-to-an-agent |
| Write a new tool | echo-sdk/tools (+ echo-sdk/models for tool_context) |
| Wrap an MCP server | echo-sdk/tools + diagram tools-mcp-connection.md |
| Modify conversation state shape | echo-sdk/models — careful, immutability is load-bearing |
| Fetch prompts from Langfuse | echo-sdk/prompts |
| Run an experiment / eval | echo-sdk/evals |
| Query Postgres from a tool | echo-sdk/databases |
| Transcribe audio | echo-sdk/audio |
These python skills apply to every task in this repo — load them when relevant:
python/async-discipline — no blocking calls in async codepython/orjson-only — never stdlib jsonpython/optional-deps — guard provider importspython/pydantic-v2 — config/schemaspython/memory-safety — close async resources (MCP managers, asyncpg pools, httpx clients)ConversationContext is immutable from the caller — return updated, don't mutate.get_*() factory; never wire concrete classes into callers.try/except ImportError with a clear install hint.orjson not json.AsyncGenerator[StreamEvent].system_context.tool_context) is injected by the LLM layer — tools receive these as kwargs; the LLM never sees them in input_schema.BaseAgent subclasses → use get_llm(LLMConfig(...)).import boto3 at module top → wrap in optional-deps guard.context.messages inside a tool → tools return values; the LLM layer appends.BaseTool.to_<provider>_schema().user_id in tool args → put it in system_context.tool_context, it's injected.Recipe for adding a new provider (LLM, transcriber, eval, prompt). Use whenever adding Cohere, Mistral, Deepgram, Phoenix, Promptlayer, etc. — anything that plugs into an existing get_*() factory.
End-to-end recipe for defining a Skill bundle and wiring it into a GenericAgent with the right activation mode and tool registry. Use when extending agent capability via swappable skills rather than baking tools in.
Building agents with BaseAgent / GenericAgent, including skill registration, activation modes (llm vs manual), and system-prompt composition. Use when editing src/echo/agents/ or building a new agent subclass.
Audio transcription provider abstraction (Gemini, EkaCare). Use when transcribing audio, adding a new transcriber, or shaping AudioInput.
Postgres support — asyncpg client, schema-aware binder, PgQueryTool surface. Use when querying postgres from a tool, modifying the binder, or adding a new DB engine.
Evaluation provider abstraction for dataset experiments (Langfuse today). Use when running an experiment, adding a new eval backend, or wiring evals into CI.