pydantic_ai.ag_ui
为 Pydantic AI 代理提供一个 AG-UI 协议适配器。
此包提供了 pydantic-ai 代理与 ag-ui 之间的无缝集成,用于构建具有流式事件通信的交互式 AI 应用程序。
AGUIApp
基类:Generic[AgentDepsT, OutputDataT]
, Starlette
用于运行支持 AG-UI 协议的 Pydantic AI 代理的 ASGI 应用程序。
源代码位于 pydantic_ai_slim/pydantic_ai/ag_ui.py
119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 |
|
__init__
__init__(
agent: AbstractAgent[AgentDepsT, OutputDataT],
*,
output_type: OutputSpec[Any] | None = None,
model: Model | KnownModelName | str | None = None,
deps: AgentDepsT = None,
model_settings: ModelSettings | None = None,
usage_limits: UsageLimits | None = None,
usage: RunUsage | None = None,
infer_name: bool = True,
toolsets: (
Sequence[AbstractToolset[AgentDepsT]] | None
) = None,
debug: bool = False,
routes: Sequence[BaseRoute] | None = None,
middleware: Sequence[Middleware] | None = None,
exception_handlers: (
Mapping[Any, ExceptionHandler] | None
) = None,
on_startup: Sequence[Callable[[], Any]] | None = None,
on_shutdown: Sequence[Callable[[], Any]] | None = None,
lifespan: (
Lifespan[AGUIApp[AgentDepsT, OutputDataT]] | None
) = None
) -> None
一个 ASGI 应用程序,通过运行代理来处理每个 AG-UI 请求。
请注意,除了注入到实现了 StateHandler
协议的 deps
对象的 state
字段中的 AG-UI 状态外,每个请求的 deps
都是相同的。要为每个请求提供不同的 deps
(例如,基于已认证的用户),请改用 pydantic_ai.ag_ui.run_ag_ui
或 pydantic_ai.ag_ui.handle_ag_ui_request
。
参数
名称 | 类型 | 描述 | 默认值 |
---|---|---|---|
agent
|
AbstractAgent[AgentDepsT, OutputDataT]
|
要运行的代理。 |
必需 |
output_type
|
OutputSpec[Any] | None
|
用于本次运行的自定义输出类型,仅当代理没有输出验证器时才可使用 |
None
|
model
|
Model | KnownModelName | str | None
|
用于本次运行的可选模型,如果在创建代理时未设置 |
None
|
deps
|
AgentDepsT
|
用于本次运行的可选依赖项。 |
None
|
model_settings
|
ModelSettings | None
|
用于此模型请求的可选设置。 |
None
|
usage_limits
|
UsageLimits | None
|
对模型请求次数或令牌用量的可选限制。 |
None
|
usage
|
RunUsage | None
|
可选的初始用量,对于恢复对话或在工具中使用的代理非常有用。 |
None
|
infer_name
|
bool
|
在未设置代理名称时,是否尝试从调用帧中推断代理名称。 |
True
|
toolsets
|
Sequence[AbstractToolset[AgentDepsT]] | None
|
用于本次运行的可选附加工具集。 |
None
|
debug
|
bool
|
一个布尔值,指示在出错时是否应返回调试追溯信息。 |
False
|
routes
|
Sequence[BaseRoute] | None
|
用于处理传入 HTTP 和 WebSocket 请求的路由列表。 |
None
|
middleware
|
Sequence[Middleware] | None
|
为每个请求运行的中间件列表。一个 starlette 应用程序总是会自动包含两个中间件类。 |
None
|
exception_handlers
|
Mapping[Any, ExceptionHandler] | None
|
将整数状态码或异常类类型映射到处理异常的可调用对象的映射。异常处理可调用对象的形式应为 |
None
|
on_startup
|
Sequence[Callable[[], Any]] | None
|
在应用程序启动时运行的可调用对象列表。启动处理可调用对象不接受任何参数,可以是标准函数或异步函数。 |
None
|
on_shutdown
|
Sequence[Callable[[], Any]] | None
|
在应用程序关闭时运行的可调用对象列表。关闭处理可调用对象不接受任何参数,可以是标准函数或异步函数。 |
None
|
lifespan
|
Lifespan[AGUIApp[AgentDepsT, OutputDataT]] | None
|
一个生命周期上下文函数,可用于执行启动和关闭任务。这是一种较新的风格,取代了 |
None
|
源代码位于 pydantic_ai_slim/pydantic_ai/ag_ui.py
122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 |
|
handle_ag_ui_request 异步
handle_ag_ui_request(
agent: AbstractAgent[AgentDepsT, Any],
request: Request,
*,
output_type: OutputSpec[Any] | None = None,
model: Model | KnownModelName | str | None = None,
deps: AgentDepsT = None,
model_settings: ModelSettings | None = None,
usage_limits: UsageLimits | None = None,
usage: RunUsage | None = None,
infer_name: bool = True,
toolsets: (
Sequence[AbstractToolset[AgentDepsT]] | None
) = None
) -> Response
通过运行代理并返回流式响应来处理 AG-UI 请求。
参数
名称 | 类型 | 描述 | 默认值 |
---|---|---|---|
agent
|
AbstractAgent[AgentDepsT, Any]
|
要运行的代理。 |
必需 |
request
|
请求
|
包含 AG-UI 运行输入的 Starlette 请求(例如,来自 FastAPI)。 |
必需 |
output_type
|
OutputSpec[Any] | None
|
用于本次运行的自定义输出类型,仅当代理没有输出验证器时才可使用 |
None
|
model
|
Model | KnownModelName | str | None
|
用于本次运行的可选模型,如果在创建代理时未设置 |
None
|
deps
|
AgentDepsT
|
用于本次运行的可选依赖项。 |
None
|
model_settings
|
ModelSettings | None
|
用于此模型请求的可选设置。 |
None
|
usage_limits
|
UsageLimits | None
|
对模型请求次数或令牌用量的可选限制。 |
None
|
usage
|
RunUsage | None
|
可选的初始用量,对于恢复对话或在工具中使用的代理非常有用。 |
None
|
infer_name
|
bool
|
在未设置代理名称时,是否尝试从调用帧中推断代理名称。 |
True
|
toolsets
|
Sequence[AbstractToolset[AgentDepsT]] | None
|
用于本次运行的可选附加工具集。 |
None
|
返回
类型 | 描述 |
---|---|
响应
|
一个带有 AG-UI 协议事件的流式 Starlette 响应。 |
源代码位于 pydantic_ai_slim/pydantic_ai/ag_ui.py
212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 |
|
run_ag_ui 异步
run_ag_ui(
agent: AbstractAgent[AgentDepsT, Any],
run_input: RunAgentInput,
accept: str = SSE_CONTENT_TYPE,
*,
output_type: OutputSpec[Any] | None = None,
model: Model | KnownModelName | str | None = None,
deps: AgentDepsT = None,
model_settings: ModelSettings | None = None,
usage_limits: UsageLimits | None = None,
usage: RunUsage | None = None,
infer_name: bool = True,
toolsets: (
Sequence[AbstractToolset[AgentDepsT]] | None
) = None
) -> AsyncIterator[str]
使用 AG-UI 运行输入来运行代理,并流式传输 AG-UI 协议事件。
参数
名称 | 类型 | 描述 | 默认值 |
---|---|---|---|
agent
|
AbstractAgent[AgentDepsT, Any]
|
要运行的代理。 |
必需 |
run_input
|
RunAgentInput
|
包含 thread_id、run_id、messages 等的 AG-UI 运行输入。 |
必需 |
accept
|
str
|
运行的 accept 标头值。 |
SSE_CONTENT_TYPE
|
output_type
|
OutputSpec[Any] | None
|
用于本次运行的自定义输出类型,仅当代理没有输出验证器时才可使用 |
None
|
model
|
Model | KnownModelName | str | None
|
用于本次运行的可选模型,如果在创建代理时未设置 |
None
|
deps
|
AgentDepsT
|
用于本次运行的可选依赖项。 |
None
|
model_settings
|
ModelSettings | None
|
用于此模型请求的可选设置。 |
None
|
usage_limits
|
UsageLimits | None
|
对模型请求次数或令牌用量的可选限制。 |
None
|
usage
|
RunUsage | None
|
可选的初始用量,对于恢复对话或在工具中使用的代理非常有用。 |
None
|
infer_name
|
bool
|
在未设置代理名称时,是否尝试从调用帧中推断代理名称。 |
True
|
toolsets
|
Sequence[AbstractToolset[AgentDepsT]] | None
|
用于本次运行的可选附加工具集。 |
None
|
产生
类型 | 描述 |
---|---|
AsyncIterator[str]
|
根据 accept 标头值编码为字符串的流式事件块。 |
源代码位于 pydantic_ai_slim/pydantic_ai/ag_ui.py
272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 |
|
StateHandler
基类:Protocol
代理运行中状态处理器的协议。要求该类是一个数据类,并带有一个 state
字段。
源代码位于 pydantic_ai_slim/pydantic_ai/ag_ui.py
608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 |
|
state 属性
可写
state: State
获取代理运行的当前状态。
StateDeps 数据类
基类:Generic[StateT]
提供 AG-UI 状态管理。
此类用于管理代理运行的状态。它允许使用特定类型的状态模型来设置代理运行的状态,该模型必须是 BaseModel
的子类。
在运行开始时,状态由 Adapter
通过 state
设置器进行设置。
实现了 StateHandler
协议。
源代码位于 pydantic_ai_slim/pydantic_ai/ag_ui.py
641 642 643 644 645 646 647 648 649 650 651 652 653 654 |
|