name: agentica-intro description: "Agentica 框架介绍。当用户询问 Agentica 的功能、如何创建 Agent、使用工具、配置模型或构建 AI 应用时使用此技能。" trigger: /agentica-intro metadata: emoji: "🤖"

Agentica Framework

GitHub: https://github.com/shibing624/agentica

Agentica 是一个轻量级、功能强大的 Python 框架，用于构建、管理和部署自主 AI 智能体。

安装

pip install -U agentica

快速开始

import asyncio
from agentica import Agent, ZhipuAI, WeatherTool

async def main():
    agent = Agent(
        model=ZhipuAI(),  # or OpenAIChat, DeepSeek, Moonshot, etc.
        tools=[WeatherTool()],
    )
    result = await agent.run("明天北京天气怎么样？")
    print(result.content)

if __name__ == "__main__":
    asyncio.run(main())

核心组件

1. Agent 类型

Agent	用途
`Agent`	基础智能体，支持工具调用和记忆
`DeepAgent`	增强智能体，内置文件、Shell、Web 等工具

from agentica import DeepAgent, OpenAIChat

agent = DeepAgent(
    model=OpenAIChat(id="gpt-4o"),
    work_dir="./project",  # 工作目录
    debug=True,       # 调试模式
)

2. 支持的模型

from agentica import (
    OpenAIChat,    # GPT-4o, GPT-4o-mini
    ZhipuAI,       # GLM-4-Flash (免费), GLM-4
    DeepSeek,      # DeepSeek-Chat, DeepSeek-Reasoner
    Moonshot,      # Moonshot-v1-8k
    Claude,        # Claude-3.5-Sonnet
)

# 配置 API Key
model = OpenAIChat(
    id="gpt-4o",
    api_key="sk-...",  # 或使用环境变量 OPENAI_API_KEY
)

3. 内置工具

from agentica.tools import (
    ShellTool,        # Shell 命令执行
    CalculatorTool,   # 数学计算
    WikipediaTool,    # Wikipedia 搜索
    BrowserTool,      # 网页浏览
    DalleTool,        # 图像生成
    WeatherTool,      # 天气查询
    BaiduSearchTool,  # 百度搜索
)

agent = Agent(model=model, tools=[ShellTool(), CalculatorTool()])

4. Workspace 与 Memory

from agentica import DeepAgent
from agentica.workspace import Workspace

# 创建 Workspace 持久化记忆
workspace = Workspace(user_id="alice")
workspace.initialize()

agent = DeepAgent(model=model, workspace=workspace)
# Agent 自动保存/加载记忆

Memory 结构：

~/.agentica/workspace/
├── AGENT.md      # Agent 指令
├── skills/       # 自定义技能
└── users/
    └── {user_id}/
        ├── USER.md      # 用户信息
        ├── MEMORY.md    # 长期记忆
        └── memory/      # 每日记忆

5. 技能系统 (Skills)

Skills 是基于 Prompt Engineering 的能力扩展，通过 SKILL.md 注入指令到 System Prompt。

from agentica.skills import load_skills

registry = load_skills()
# 技能自动注入到 Agent

技能目录：

{project_root}/.agentica/skills/ - 项目级
~/.agentica/skills/ - 用户级
内置技能：agentica-intro, commit, github, skill-creator

CLI 使用

# 交互模式
agentica

# 指定模型
agentica --model_provider deepseek --model_name deepseek-chat

# 添加工具
agentica --tools calculator shell wikipedia

# 单次查询
agentica --query "Python 最佳实践是什么？"

CLI 快捷键：

Enter - 提交消息
Ctrl+X - 切换 Shell 模式
Ctrl+D - 退出
@file - 引用文件
/help - 显示命令

高级功能

多 Agent 协作

from agentica import DeepAgent
from agentica.subagent import Subagent

# 创建专业子 Agent
researcher = Subagent(
    name="researcher",
    description="Research specialist",
    model=model,
)

# 主 Agent 通过 'task' 工具委派任务
main_agent = DeepAgent(
    model=model,
    description="Coordinator",
)

工作流编排

from agentica.workflow import Workflow

workflow = Workflow(
    agents=[agent1, agent2, agent3],
    description="Research and report workflow",
)
workflow.run("Generate market analysis report")

RAG 知识库

import asyncio
from agentica import Agent
from agentica.knowledge import PDFKnowledgeBase

kb = PDFKnowledgeBase(path="./docs")
agent = Agent(model=model, knowledge=kb)
asyncio.run(agent.print_response("文档中关于 X 的内容是什么？"))

MCP 协议支持

Agent 支持加载 mcp_config.json 配置文件（搜索顺序：当前目录 → 父目录 → ~/.agentica/）：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem"],
      "timeout": 60.0,
      "enable": true
    },
    "disabled-server": {
      "command": "some-command",
      "enable": false
    }
  }
}

enable: 是否启用该 MCP 服务器，默认 true，设为 false 禁用
auto_load_mcp: Agent 参数，默认 False，设为 True 启用自动加载

代码中使用：

from agentica import Agent

# 启用自动加载 MCP 配置
agent = Agent(model=model, auto_load_mcp=True)

# 默认不加载（适用于不支持工具的模型）
agent = Agent(model=model)

# 手动加载
from agentica.tools.mcp_tool import McpTool
mcp_tool = McpTool.from_config()
agent = Agent(model=model, tools=[mcp_tool], auto_load_mcp=False)

环境变量

# API Keys
export OPENAI_API_KEY="sk-..."
export ZHIPUAI_API_KEY="..."
export DEEPSEEK_API_KEY="..."

# Workspace 路径（可选）
export AGENTICA_WORKSPACE_DIR="~/.agentica/workspace"

最佳实践

使用 DeepAgent - 大多数任务推荐，内置必要工具
设置 work_dir - 控制文件操作范围
启用 debug - 开发时查看工具调用
使用 Workspace - 持久化跨会话记忆
创建 Skills - 复杂重复工作流封装为技能

Name	agentica-intro
Description	Agentica 框架介绍。当用户询问 Agentica 的功能、如何创建 Agent、使用工具、配置模型或构建 AI 应用时使用此技能。

agentica-intro

SKILL.md