需要构建或调试 Python AI Agent 时：用…

在 Python 项目中基于 Agentica SDK v0.3.1 创建可调用函数、可维护状态、可使用工具并可互相编排的 AI agent。

适用场景

解决思路

1. 导入并使用 Agentica SDK v0.3.1；从 `agentica` 导入核心对象：`Agent`、`agentic`、`spawn`、`ModelStrings`、`AgenticFunction`、`last_usage`、`total_usage`、`initialize_tracing`、`enable_sdk_logging`、`__version__`。
2. 用 `@agentic()` 定义最简单的 agentic 函数：函数必须用 `async def`，返回类型注解即结果类型；示例：`from agentica import agentic; @agentic(); async def add(a: int, b: int) -> int: ...; result = await add(1, 2)`。
3. 用 `spawn()` 创建可控 agent：`from agentica import spawn; agent = await spawn(premise='You are a truth-teller.'); result: bool = await agent.call(bool, 'The Earth is flat')`。
4. 按需指定 `agent.call()` 返回类型：默认返回字符串用 `await agent.call('What is 2+2?')`；返回整数用 `await agent.call(int, 'What is 2+2?')`；返回字典用 `await agent.call(dict[str, int], 'Count items')`；只产生副作用用 `await agent.call(None, 'Send message to John')`。
5. 用 `premise` 参数给默认 system prompt 追加设定：`await spawn(premise='You are a math expert.')`。
6. 用 `system` 参数完全替换默认 system prompt：`await spawn(system='You are a JSON-only responder.')`。
7. 通过 `scope` 传入工具：在装饰器中 `@agentic(scope={'web_search': web_search_fn})`；在 spawn 中 `await spawn(premise='Data analyzer', scope={'analyze': custom_analyzer})`；每次调用传 scope：`await agent.call(dict[str, int], 'Analyze the dataset', dataset=data, analyzer=custom_fn)`。
8. 集成已有 SDK：以 Slack 为例，`from slack_sdk import WebClient; slack = WebClient(token=SLACK_TOKEN); @agentic(scope={'list_users': slack.users_list, 'send_message': slack.chat_postMessage}); async def team_notifier(message: str) -> None: ...`。
9. 异步场景优先用 `spawn()`：`agent = await spawn(premise='Helpful assistant')`。
10. 同步 `__init__` 中用 `Agent()` 而非 `spawn()`：`from agentica.agent import Agent; class CustomAgent: def __init__(self): self._brain = Agent(premise='Specialized assistant', scope={'tool': some_tool}); async def run(self, task: str) -> str: return await self._brain(str, task)`。
11. 选择模型：spawn 中传 `model='openai:gpt-5'`，默认是 `openai:gpt-4.1`；@agentic 中传 `@agentic(model='anthropic:claude-sonnet-4.5')`。
12. 可用模型包括：`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`。
13. 让 `@agentic` 函数持久化状态：用 `@agentic(persist=True)`，同一函数可记住对话历史，如先 `await chatbot('My name is Alice')` 再 `await chatbot('What's my name?')`。
14. `spawn()` 创建的 agent 在同一实例上的多次调用自动保持状态。
15. 设置简单 token 上限：`await spawn(premise='Brief responses', max_tokens=500)`。
16. 设置细粒度 token 上限：`MaxTokens(per_invocation=5000, per_round=1000, rounds=5)`。
17. 追踪 token 用量：导入 `last_usage, total_usage`；对 agent 用 `agent.last_usage()`、`agent.total_usage()`；对 @agentic 函数用 `last_usage(my_fn)`、`total_usage(my_fn)`。
18. 流式输出：`from agentica.logging.loggers import StreamLogger; import asyncio; stream = StreamLogger(); with stream: result = asyncio.create_task(agent.call(bool, 'Is Paris the capital of France?'))`；先 `async for chunk in stream: print(chunk.content, end='', flush=True)` 消费流，`chunk.role` 为 `user`、`agent` 或 `system`，最后 `final = await result`。
19. 集成 MCP：`agent = await spawn(premise='Tool-using agent', mcp='path/to/mcp_config.json')` 或 `@agentic(mcp='path/to/mcp_config.json')`。
20. 编写 `mcp_config.json`：使用 `mcpServers` 对象，例如 `{'mcpServers': {'tavily-remote-mcp': {'command': 'npx -y mcp-remote https://mcp.tavily.com/mcp/?tavilyApiKey=<key>', 'env': {}}}}`。
21. 了解默认日志行为：打印彩色 stdout，并写入 `./logs/agent-<id>.log`。
22. 用上下文管理器控制日志：从 `agentica.logging.loggers` 导入 `FileLogger`、`PrintLogger`，从 `agentica.logging.agent_logger` 导入 `NoLogging`；`with FileLogger(): ...` 只写文件；`with NoLogging(): ...` 静默。
23. 按 agent 设置日志：从 `agentica.logging.agent_listener` 导入 `PrintOnlyListener`、`FileOnlyListener`、`StandardListener`、`NoopListener`，然后 `await spawn(premise='Custom logging', listener=PrintOnlyListener)`；静默用 `listener=NoopListener`。
24. 全局设置默认日志监听器：`from agentica.logging.agent_listener import set_default_agent_listener, get_default_agent_listener, PrintOnlyListener; set_default_agent_listener(PrintOnlyListener); set_default_agent_listener(None)`。
25. 处理 SDK 错误：从 `agentica.errors` 导入 `AgenticaError`、`RateLimitError`、`InferenceError`、`MaxTokensError`、`MaxRoundsError`、`ContentFilteringError`、`APIConnectionError`、`APITimeoutError`、`InsufficientCreditsError`、`OverloadedError`、`ServerError`；`RateLimitError` 时 `await asyncio.sleep(60)` 后重试；`MaxTokensError` 时减小 scope 或提高限制；`ContentFilteringError` 按内容被过滤处理；`InferenceError` 记录日志；`AgenticaError` 记录 SDK 错误。
26. 定义自定义异常：`class DataValidationError(Exception): ...; @agentic(DataValidationError); async def analyze(data: str) -> dict: ...`；在 docstring 的 Raises 中声明异常，然后在 `try/except DataValidationError` 中处理。
27. 用自定义 Agent 类组织多代理：`from agentica.agent import Agent; class ResearchAgent: def __init__(self, web_search_fn): self._brain = Agent(premise='Research assistant.', scope={'web_search': web_search_fn}); async def research(self, topic: str) -> str: return await self._brain(str, f'Research: {topic}'); async def summarize(self, text: str) -> str: return await self._brain(str, f'Summarize: {text}')`。
28. 编排多代理：`class LeadResearcher: def __init__(self): self._brain = Agent(premise='Coordinate research across subagents.', scope={'SubAgent': ResearchAgent}); async def __call__(self, query: str) -> str: return await self._brain(str, query)`；然后 `lead = LeadResearcher(); report = await lead('Research AI agent frameworks 2025')`。
29. 启用 OpenTelemetry 追踪：`from agentica import initialize_tracing; tracer = initialize_tracing(service_name='my-agent-app', environment='development', tempo_endpoint='http://localhost:4317', organization_id='my-org', log_level='INFO', instrument_httpx=False)`。
30. 调试 SDK 本身：`from agentica import enable_sdk_logging; disable_fn = enable_sdk_logging(log_tags='1')`，运行 agent 后调用 `disable_fn()`。
31. 遵守使用检查清单：@agentic 函数必须为 async；`spawn()` 返回 awaitable，必须 `await spawn(...)`；`agent.call()` 必须 `await`；`call()` 第一个参数是返回类型，第二个是 prompt 字符串；@agentic 用 `persist=True` 获得对话记忆；同步 `__init__` 中用 `Agent()` 而不是 `spawn()`；在 docstring 中记录异常以便 agent 抛出；listener 从 `agentica.logging.agent_listener` 导入而不是 `agentica.logging`。

适用边界 · 注意事项

• 非 Python 项目，或不想引入 Agentica SDK、模型服务/API Key、付费账号等外部依赖时。
• 运行环境不能使用 async/await 且无法把 agent 放到同步 Agent() 中承接时。
• 只需要简单脚本、不需要工具调用、状态持久化、MCP、流式、日志或追踪能力时。