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, ...) -> RunResponse
  • Agent.run_stream(message, ...) -> AsyncIterator[RunEvent]
  • Agent.run_sync(message, ...) -> RunResponse
  • Agent.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

运行配置

from agentica.run.response import RunResponse, RunEvent
from agentica.run.config import RunConfig

Hook 接口

from agentica.agent.hooks import RunHooks, AgentHooks

Workspace(默认装)

from agentica.workspace import 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

from agentica import DeepAgent

agent = 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)

agentica             # 交互式模式
agentica --query "..."

CLI 是面向最终用户的产品入口,默认使用 DeepAgent 体验。CLI 参数、权限模式、技能安装、日常任务命令和 TUI 行为属于 Product Surface,不应作为嵌入式 SDK 的最小依赖假设。

ACP(IDE 集成)— 基础安装自带,无需额外依赖

from agentica.acp import ACPServer

ACP 走 stdio NDJSON,日志与 Agent 输出一律到 stderr;协议细节、会话恢复和第三方客户端示例见 ACP 集成。

MCP(Model Context Protocol)— uv add "agentica[mcp]"

from agentica.mcp import MCPClient, MCPServer

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 符号的任何变更(新增字段、改签名、重命名、删除)必须:

  1. 在 PR 中说明变更理由与影响范围
  2. Tier 1 变更需写 RFC 到 docs/rfcs/
  3. 删除或改现有行为 → 必须 major bump
  4. 新增参数必须有默认值,不破坏现有调用
  5. CHANGELOG.md 列出变更

Tier 3 变更不要求 RFC,但建议说明 dogfood 发现与选择依据。