Python agentic-core 包详解：功能、安装、语法与案例

1. 引言

agentic-core 是 Python 生态中一个面向智能体（Agent）编排与执行的轻量级核心库，它把「工具调用、上下文管理、多步推理、任务循环」等能力封装成简洁的 API，让开发者可以快速搭建可复用的智能体应用。本文将从功能定位、安装方式、核心语法与参数入手，再通过 16 个实际应用案例演示典型用法，最后总结常见错误与使用注意事项。

2. 功能概述

agentic-core 的核心设计目标是「把智能体的骨架与业务逻辑解耦」。它主要提供以下能力：

• 任务编排：以步骤（Step）为单位组织多阶段流程，支持顺序、分支和循环。
• 工具注册与调用：通过装饰器或注册表把普通 Python 函数暴露为可被模型调用的工具。
• 上下文管理：维护会话级和步骤级的上下文对象，支持变量读写与状态传递。
• 模型无关接口：内置对大模型 API 的适配层，可切换不同厂商的模型。
• 可观测性：提供日志、追踪和回调钩子，便于调试多步执行过程。
• 可扩展性：支持自定义步骤、自定义工具解析器和自定义记忆后端。

3. 安装方式

agentic-core 通过 pip 分发，建议在虚拟环境中安装。基础安装命令如下：

pip install agentic-core

如果需要使用内置的 OpenAI 兼容接口，可以安装扩展依赖：

pip install "agentic-core[openai]"

安装完成后，可以通过以下方式验证版本：

import agentic_core print(agentic_core.__version__)

4. 核心语法与参数

4.1 创建智能体

Agent 是 agentic-core 的顶层入口，负责把模型、工具和步骤串联起来。常用参数如下：

from agentic_core import Agent agent = Agent( model="gpt-4o-mini", api_key="your-api-key", system_prompt="你是一个乐于助人的助手。", max_steps=10, temperature=0.2, verbose=True, )

• model：模型名称，字符串类型。
• api_key：API 密钥，也可通过环境变量注入。
• system_prompt：系统提示词，用于设定角色和行为边界。
• max_steps：单次任务允许的最大推理步数，防止死循环。
• temperature：采样温度，控制输出的随机性。
• verbose：是否打印执行日志。

4.2 注册工具

工具是智能体与外部世界交互的桥梁。agentic-core 支持用装饰器快速注册：

from agentic_core import tool @tool(description="计算两个数字的和") def add(a: float, b: float) -> float: """返回 a 与 b 的和。""" return a + b agent.register_tool(add)

工具函数的类型注解会被自动解析为参数 schema，供模型按需调用。

4.3 执行任务

执行任务时，把用户请求传入 run 方法即可：

result = agent.run("请计算 12 和 30 的和") print(result.output)

run 方法返回一个结果对象，包含最终输出、执行轨迹和消耗的步数。

4.4 步骤与流程控制

对于复杂任务，可以显式定义步骤序列：

from agentic_core import Step, Workflow step1 = Step(name="解析需求", action="parse") step2 = Step(name="调用工具", action="tool_call", tool_name="add") workflow = Workflow(steps=[step1, step2]) agent.run_workflow(workflow, user_input="计算 1+2")

5. 16 个实际应用案例

案例 1：基础问答

最简单的用法是让智能体直接回答用户问题，不涉及工具调用。

from agentic_core import Agent agent = Agent(model="gpt-4o-mini", api_key="sk-xxx") resp = agent.run("用一句话解释什么是递归") print(resp.output)

案例 2：数学计算工具

注册一个计算器工具，让模型在需要时自动调用。

from agentic_core import Agent, tool @tool(description="执行四则运算") def calc(expr: str) -> str: return str(eval(expr)) agent = Agent(model="gpt-4o-mini", api_key="sk-xxx") agent.register_tool(calc) print(agent.run("计算 (3+5)*2 的结果").output)

案例 3：天气查询

通过模拟天气 API 演示工具参数解析。

@tool(description="查询指定城市的天气") def get_weather(city: str) -> str: data = {"北京": "晴 25°C", "上海": "多云 28°C"} return data.get(city, "暂无数据") agent.register_tool(get_weather) print(agent.run("北京今天天气怎么样？").output)

案例 4：多工具协作

同时注册多个工具，让模型根据任务自主选择。

@tool(description="获取用户订单状态") def get_order(order_id: str) -> str: return f"订单 {order_id} 已发货" @tool(description="获取物流轨迹") def get_tracking(order_id: str) -> str: return "已到达本地分拨中心" agent.register_tool(get_order) agent.register_tool(get_tracking) print(agent.run("查询订单 A123 的状态和物流").output)

案例 5：带记忆的多轮对话

开启会话记忆，让智能体记住前文内容。

agent = Agent( model="gpt-4o-mini", api_key="sk-xxx", memory=True, memory_size=10, ) agent.run("我叫小明") print(agent.run("我叫什么名字？").output)

案例 6：自定义系统提示词

通过 system_prompt 约束输出风格。

agent = Agent( model="gpt-4o-mini", api_key="sk-xxx", system_prompt="你是一位严谨的数学老师，回答必须给出推导过程。", ) print(agent.run("为什么 0 不能做除数？").output)

案例 7：结构化输出解析

让模型返回 JSON，并自动解析为 Python 对象。

from agentic_core import OutputParser class UserInfo(OutputParser): schema = {"name": "str", "age": "int"} agent = Agent(model="gpt-4o-mini", api_key="sk-xxx") resp = agent.run("提取这句话里的人名和年龄：张三今年 18 岁") print(resp.parse(UserInfo))

案例 8：步骤化工作流

用 Workflow 显式编排多阶段任务。

from agentic_core import Step, Workflow s1 = Step(name="提取关键词", action="extract") s2 = Step(name="生成摘要", action="summarize") wf = Workflow(steps=[s1, s2]) agent = Agent(model="gpt-4o-mini", api_key="sk-xxx") print(agent.run_workflow(wf, "请总结这篇文章的核心观点").output)

案例 9：条件分支

根据中间结果决定后续执行路径。

from agentic_core import Step, Workflow, If s1 = Step(name="判断情感", action="sentiment") branch = If(condition="sentiment == 'negative'", then_step=Step(name="安抚用户", action="comfort"), else_step=Step(name="正常回复", action="reply")) wf = Workflow(steps=[s1, branch]) agent.run_workflow(wf, "这个产品太差了")

案例 10：循环执行

使用循环步骤反复处理数据，直到满足退出条件。

from agentic_core import Step, Workflow, Loop loop = Loop( step=Step(name="处理一行", action="process_line"), until="所有行处理完毕", ) wf = Workflow(steps=[loop]) agent.run_workflow(wf, "逐行处理以下数据：...")

案例 11：自定义回调钩子

通过回调监听每一步的执行状态。

def on_step_end(step_name, result): print(f"步骤 {step_name} 完成，结果：{result}") agent = Agent(model="gpt-4o-mini", api_key="sk-xxx") agent.add_callback("on_step_end", on_step_end) agent.run("完成一个三步任务")

案例 12：错误重试机制

当工具调用失败时自动重试。

agent = Agent( model="gpt-4o-mini", api_key="sk-xxx", retry_times=3, retry_delay=1.0, ) print(agent.run("调用一个可能失败的工具").output)

案例 13：超时控制

限制单次任务的最大执行时间。

agent = Agent( model="gpt-4o-mini", api_key="sk-xxx", timeout=30, ) print(agent.run("执行一个长任务").output)

案例 14：流式输出

开启流式模式，逐 token 返回结果。

agent = Agent(model="gpt-4o-mini", api_key="sk-xxx", stream=True) for chunk in agent.run_stream("写一首短诗"): print(chunk, end="")

案例 15：批量任务处理

用同一个智能体并发处理多条请求。

from agentic_core import batch_run questions = ["1+1=?", "2+2=?", "3+3=?"] results = batch_run(agent, questions, max_concurrency=3) for r in results: print(r.output)

案例 16：自定义记忆后端

把会话记忆持久化到 Redis 或数据库。

from agentic_core import RedisMemory memory = RedisMemory(host="localhost", port=6379) agent = Agent( model="gpt-4o-mini", api_key="sk-xxx", memory=memory, ) print(agent.run("记住我的偏好：喜欢简洁回答").output)

6. 常见错误与使用注意事项

6.1 常见错误

6.2 使用注意事项

• 密钥安全：不要把 API Key 硬编码在代码中，建议使用环境变量或密钥管理服务。
• 工具函数保持纯净：工具内部尽量避免副作用，便于调试和复用。
• 合理设置 max_steps：过小会导致任务中断，过大会增加成本和延迟。
• 注意 token 成本：长上下文和多次工具调用会显著增加费用，建议开启日志监控。
• 版本兼容：升级 agentic-core 前先阅读 changelog，避免破坏性变更影响现有代码。
• 错误处理：建议为 run 方法包裹 try-except，捕获网络超时和限流异常。

7. 总结

agentic-core 以简洁的 API 封装了智能体开发中的常见痛点，从工具注册、步骤编排到记忆管理都有对应的解决方案。通过本文的 16 个案例，读者可以快速上手并在此基础上扩展自己的业务场景。在实际使用中，建议结合日志、回调与重试机制，逐步构建稳定可靠的智能体应用。

《动手学PyTorch建模与应用:从深度学习到大模型》是一本从零基础上手深度学习和大模型的PyTorch实战指南。全书共11章，前6章涵盖深度学习基础，包括张量运算、神经网络原理、数据预处理及卷积神经网络等；后5章进阶探讨图像、文本、音频建模技术，并结合Transformer架构解析大语言模型的开发实践。书中通过房价预测、图像分类等案例讲解模型构建方法，每章附有动手练习题，帮助读者巩固实战能力。内容兼顾数学原理与工程实现，适配PyTorch框架最新技术发展趋势。