Agentica SDK 是一个使用 Python 构建 AI 智能体的开发框架，本参考文档对应版本 v0.3.1。智能体可以在此框架下实现函数、维护状态、使用工具，并彼此协调。
一、适用场景 资料列出以下适用情形：构建新的 Python 智能体；为已有代码增加 agentic 能力；将 MCP 工具与智能体集成；实现多智能体编排；调试智能体行为。
二、快速开始 最简单的形式是 agentic 函数：
from agentica import agentic
@agentic() async def add(a: int, b: int) -> int: """Returns the sum of a and b""" ...
result = await add(1, 2) # Agent computes: 3
另一种是 spawn 生成智能体，控制更细：
from agentica import spawn
agent = await spawn(premise="You are a truth-teller.") result: bool = await agent.call(bool, "The Earth is flat")
Returns: False
三、核心模式 返回类型：可以返回字符串（默认），也可以指定类型化输出，如 int、dict[str, int]，或使用 None 表示仅产生副作用。
Premise 与 System Prompt：premise 会追加到默认系统提示；system 则完全替换默认系统提示，例如 spawn(system="You are a JSON-only responder.")。
传递工具（Scope）：可以在 @agentic 装饰器中传入 scope 字典，也可以在 spawn 中传入 scope，或在每次 call 时按调用传入（如 dataset=data、analyzer=custom_fn）。文档还给出与第三方 SDK 集成的示例，例如从 slack_sdk 的 WebClient 中抽取 list_users 与 send_message 方法，注入到 @agentic 的 scope 中。
四、智能体实例化 spawn() 为异步方式，适用于多数情况；Agent() 为同步方式，适用于 init 中。文档给出自定义 Agent 类的示例，在同步 init 中使用 Agent(premise=..., scope=...) 创建内部 brain，并在异步 run 方法中调用。
五、模型选择 可在 spawn 或 @agentic 中通过 model 参数指定。文档提到默认模型为 openai:gpt-4.1，可用模型包括：openai:gpt-3.5-turbo、openai:gpt-4o、openai:gpt-4.1、openai:gpt-5；anthropic:claude-sonnet-4、anthropic:claude-opus-4.1、anthropic:claude-sonnet-4.5、anthropic:claude-opus-4.5；以及任何 OpenRouter slug（例如 google/gemini-2.5-flash）。
六、持久化（有状态智能体） 在 @agentic 上使用 persist=True，可记住对话历史，示例中智能体能记住用户名字。对于 spawn 创建的智能体，同一实例跨调用自动保持状态。
七、Token 限制与用量追踪 可通过 max_tokens=500 设置简单限制，或用 MaxTokens(per_invocation=5000, per_round=1000, rounds=5) 做细粒度控制。用量追踪方面，智能体实例有 last_usage() 与 total_usage() 方法；@agentic 函数则使用 last_usage(my_fn) 与 total_usage(my_fn)。
八、流式输出 可结合 StreamLogger 与 asyncio.create_task 实现：先消费 stream 以获得实时输出（chunk.role 可为 user、agent 或 system），再 await 最终结果。
九、MCP 集成 可在 spawn 或 @agentic 中通过 mcp 参数指向 MCP 配置文件路径。文档给出 mcp_config.json 格式示例，其中 mcpServers 条目包含 command 与 env 字段，并以 tavily-remote-mcp 为例。
十、日志 默认行为是带颜色输出到 stdout，并写入 ./logs/agent-<id>.log。可使用 FileLogger、PrintLogger、NoLogging 做上下文日志控制。按智能体可指定 listener，可选 PrintOnlyListener（仅控制台）、FileOnlyListener（仅文件）、StandardListener（控制台加文件，默认）、NoopListener（静默）。注意 listener 位于 agentica.logging.agent_listener 子模块，不从 agentica.logging 导出。全局配置可使用 set_default_agent_listener 与 get_default_agent_listener。
十一、错误处理 文档列出错误类型：AgenticaError（SDK 错误基类）、RateLimitError、InferenceError、MaxTokensError、MaxRoundsError、ContentFilteringError、APIConnectionError、APITimeoutError、InsufficientCreditsError、OverloadedError、ServerError，并给出捕获与重试示例。此外还可自定义异常：将异常类型传给 @agentic，并在函数 docstring 的 Raises 中说明。
十二、多智能体模式 文档给出自定义 Agent 类（ResearchAgent）以及编排示例（LeadResearcher），后者在 scope 中注入 SubAgent。
十三、追踪与调试 可使用 initialize_tracing 初始化 OpenTelemetry 追踪，返回 TracerProvider，可设置 service_name、environment、tempo_endpoint、organization_id、log_level、instrument_httpx 等参数。也可使用 enable_sdk_logging(log_tags="1") 启用 SDK 内部日志，返回的 disable_fn 可用于关闭。
十四、顶层导出 从 agentica 可导入：Agent、agentic、spawn、ModelStrings、AgenticFunction、last_usage、total_usage、initialize_tracing、enable_sdk_logging、version。
十五、使用前检查清单 文档强调：@agentic() 标记的函数必须是 async；spawn() 返回可等待对象，需 await；agent.call() 可等待，需 await；call() 第一个参数是返回类型，第二个是提示字符串；@agentic 对话记忆使用 persist=True；同步 init 中使用 Agent() 而非 spawn()；在 docstring 中说明异常以便智能体抛出；listener 需从 agentica.logging.agent_listener 导入，而非 agentica.logging。