Agentica Public API(Tier 稳定度合约)¶
适用版本:v1.6.0 及之后(1.6.0 起会话 transcript 在
agentica.session.*,旧agentica.memory.session_log等路径已删除) 维护原则:每次发版前检查本文档与代码的一致性。未列出的符号均视为 Internal,不承诺稳定。
稳定度分层¶
| Tier | 含义 | 变更规则 |
|---|---|---|
| Tier 1 | 最小稳定面 | 在 v1.x / v2.x 内不做破坏性变更;新增必须默认值 |
| Tier 2 | 主仓可选能力 | minor 内尽量不 break;major 允许调整 |
| Tier 3 | 实验 / 过渡 | 可能随时演进;文档需明确标注 |
| Internal | 内部实现 | 不承诺稳定;不建议外部直接 import |
产品分层¶
稳定度 Tier 只说明“破坏性变更风险”,不等于“默认应该使用”。Agentica 的公开能力按产品层分为四类:
+--------------------------------------------------------------+
| Product Surface |
| CLI / Gateway / ACP / scheduled daily tasks / channels |
+--------------------------------------------------------------+
| Product Presets |
| DeepAgent / future daily_preset() / coding_preset() |
+--------------------------------------------------------------+
| Stable SDK Core |
| Agent / Runner behavior via Agent.run() / RunConfig / Tool |
| Model / RunResponse / RunContext / hooks interfaces |
+--------------------------------------------------------------+
| Optional Capabilities |
| Workspace / Skills / Experience / Subagent |
+--------------------------------------------------------------+
- Stable SDK Core 是新代码的默认起点:用
Agent组合模型、工具、RunConfig和 hooks。 - Product Presets 是有观点的开箱组合:
DeepAgent默认启用文件、网页、任务、记忆、压缩和经验捕获,更适合 CLI/Gateway/dogfood,不代表最小 SDK 面。 - Product Surface 是最终用户入口:CLI、Gateway、ACP、渠道和定时任务可以使用 presets,但不应反向决定 SDK Core 的签名。
- Optional Capabilities 可与 Core 组合;只有业务确实需要持久资产、技能、自进化或多 Agent 编排时再启用。
Tier 1:核心最小稳定面¶
Agent 运行时¶
from agentica import Agent
agent = Agent(
model=..., # Required: a Model instance
tools=[...], # Optional: list of @tool-decorated functions or Tool instances
hooks=[...], # Optional: list of Hook instances
workspace=..., # Optional: Workspace instance
...
)
await agent.run(message) # async non-stream
async for evt in agent.run_stream(message): ... # async stream
agent.run_sync(message) # sync adapter (wraps run())
关键方法:
Agent.run(message, *, stream=False, ...) -> RunResponseAgent.run_stream(message, ...) -> AsyncIterator[RunEvent]Agent.run_sync(message, ...) -> RunResponseAgent.run_stream_sync(message, ...) -> Iterator[RunEvent]
Model 基础¶
from agentica.model.base import Model
from agentica.model.message import Message, UserMessage, AssistantMessage, SystemMessage, ToolMessage
from agentica.model.response import ModelResponse
Model Providers(默认装)¶
from agentica.model.openai import OpenAIChat # 默认可用
from agentica.model.anthropic.claude import Claude # 默认可用
Tool 基础¶
from agentica.tools.base import Tool, Function, FunctionCall
from agentica.tools.decorators import tool
运行配置¶
Hook 接口¶
Workspace(默认装)¶
Session Log(默认装,需显式 session_id)¶
三端写的是同一份 JSONL。Web /traces、CLI /trace /export、SDK 下面这组方法都是对这份文件的读时分析,不是第二套存储。不传 session_id 不落盘;enable_session_log=False 关掉落盘。
from agentica import Agent
from agentica.session.log import SessionLog # 也可从已有文件打开
agent = Agent(model=..., session_id="my-session-001")
log = agent.session_log # Optional[SessionLog]
log.analyze() # 与 GET /api/sessions/{id}/trace/analysis 同一 payload
log.format_trace() # 与 CLI /trace 同一份文本;format_trace(round_n=1) 展开一轮
log.export("out.jsonl") # kind="jsonl"(默认)| "analysis"
CLI 对应:/trace、/trace <n>、/export(默认拷贝 jsonl)、/status 的 Session log 行。
Web、IM 与 CLI 的会话目录由 agentica.session.catalog.list_catalog 统一产出;它是内部读模型,不列入稳定 API。
Product Presets(默认装,但有产品观点)¶
DeepAgent¶
DeepAgent 是 batteries-included preset:默认启用 builtin tools、Workspace memory、conversation archive、memory extraction、context overflow handling、tool-result compression 和 experience capture。它是 CLI/Gateway 的推荐底座,但不是最小 SDK Core;库集成默认应从 Agent 开始,再显式打开需要的能力。
Tier 2:主仓可选能力(agentica[xxx])¶
Guardrails¶
from agentica.guardrails import (
InputGuardrail, OutputGuardrail,
ToolInputGuardrail, ToolOutputGuardrail,
input_guardrail, output_guardrail,
)
Gateway — 独立发行包 agentica-gateway(产品用 uv tool install "agentica[gateway]";当库用 uv add agentica-gateway)¶
from agentica_gateway.main import app, main # FastAPI app
from agentica_gateway.channels import (
Channel, ChannelType, Message,
FeishuChannel, # 需 agentica-gateway[feishu](agentica[gateway] 已含)
TelegramChannel, # 需 agentica-gateway[telegram]
DiscordChannel, # 需 agentica-gateway[discord]
QQChannel, # 需 agentica-gateway[qq]
WeComChannel, # 需 agentica-gateway[wecom]
DingTalkChannel, # 需 agentica-gateway[dingtalk]
WeChatChannel, # 需 agentica-gateway[wechat]
)
agentica-gateway 与 agentica 同版本发布,并精确锁定同版本的 agentica。旧路径 agentica.gateway.* 已移除,请改用 agentica_gateway.*。
详见 Gateway 文档。
CLI(默认装的 Product Surface)¶
CLI 是面向最终用户的产品入口,默认使用 DeepAgent 体验。CLI 参数、权限模式、技能安装、日常任务命令和 TUI 行为属于 Product Surface,不应作为嵌入式 SDK 的最小依赖假设。
ACP(IDE 集成)— 基础安装自带,无需额外依赖¶
ACP 走 stdio NDJSON,日志与 Agent 输出一律到 stderr;协议细节、会话恢复和第三方客户端示例见 ACP 集成。
MCP(Model Context Protocol)— uv add "agentica[mcp]"¶
Tools 扩展 — 细粒度 extras¶
# uv add "agentica[arxiv]"
from agentica.tools.arxiv_tool import ArxivTool
# uv add "agentica[yfinance]"
from agentica.tools.yfinance_tool import YFinanceTool
# uv add "agentica[crawl]"
from agentica.tools.url_crawler_tool import UrlCrawlerTool
# uv add "agentica[ddg]"
from agentica.tools.duckduckgo_tool import DuckDuckGoTool
超级组合(自己的项目用 uv add;产品隔离环境用 uv tool install --force "agentica[…]"):
uv add "agentica[tools-search]" # DDG + Wikipedia + Serper + Exa + Bocha
uv add "agentica[tools-research]" # arxiv + wikipedia + newspaper + dblp
uv add "agentica[tools-finance]" # yfinance
uv add "agentica[tools-media]" # dalle + cogview + cogvideo + ocr + image/video analysis
Tier 3:实验 / 过渡能力¶
以下能力可能随时演进。新代码不建议深度依赖;现有用户可继续使用,但 major 版本可能调整。
# 子 Agent(建议新代码用 @tool + Agent() 组合)
from agentica.subagents import SubagentRegistry
# 技能 / 经验(自进化能力)
from agentica.skills import SkillRegistry
from agentica.experience import (
ExperienceCompiler,
SkillEvolutionManager,
SkillLifecycleHooks, # v1.4.3+ 扩展协议(admission / promotion / failure)
NoopSkillLifecycleHooks, # 默认 no-op 实现
)
# 压缩(引擎内部,尽量不直接依赖)
from agentica.compression import CompressionManager
Internal(不对外承诺)¶
以下模块/路径属于内部实现,外部代码不建议直接 import,API 可能在任何 patch 版本变化:
agentica._internal.*(如果未来新增)agentica.utils.markdown_converter.MarkdownConverter(内部文档转换工具)agentica.runner.Runner(Agent 的执行引擎,通过 Agent.run() 访问)agentica.compression.*(内部压缩管道)agentica.session.*的读模型(catalog/rows/trace/index/search)属内部,不承诺稳定
默认 __all__(顶层 export)¶
agentica/__init__.py 的 __all__ 保留了向后兼容的大量 export,包括便捷 alias 如:
Agent/RunResponse/RunEvent/Message...OpenAIChat/DeepSeek/Claude/ ... (所有 model provider 别名)BuiltinFileTool/BuiltinExecuteTool/CodeTool/McpTool/ ... (常用 tool)
推荐的新代码风格(明确的 import 路径,对标 agno):
# ✅ 推荐
from agentica import Agent, tool
from agentica.model.openai import OpenAIChat
from agentica.tools.builtin import BuiltinFileTool, BuiltinExecuteTool
# ✅ 也可以(顶层快捷 import 作为 v1.x 稳定 API 长期支持)
from agentica import Agent, OpenAIChat, BuiltinFileTool, BuiltinExecuteTool
变更流程¶
对 Tier 1 / Tier 2 符号的任何变更(新增字段、改签名、重命名、删除)必须:
- 在 PR 中说明变更理由与影响范围
- Tier 1 变更需写 RFC 到
docs/rfcs/ - 删除或改现有行为 → 必须 major bump
- 新增参数必须有默认值,不破坏现有调用
CHANGELOG.md列出变更
Tier 3 变更不要求 RFC,但建议说明 dogfood 发现与选择依据。