---

name: agent-core description: "Guides agents building, running, streaming, testing, and composing Pydantic AI Agent instances with dependencies, instructions, history, usage limits, specs, and handoffs." disable-model-invocation: true metadata: disco-role: operating license: MIT

Agent Core

Use this sub-skill when the task is to create, configure, run, stream, persist, test, or compose pydantic_ai.Agent instances.

Read First

• Read references/agent-api.md when choosing Agent(...), run*, iter, retry, usage-limit, dependency, or AgentSpec parameters.
• Read references/workflows.md when implementing a minimal agent, typed dependencies, streaming/events, message-history continuation, multi-agent handoff, or declarative spec loading.
• Read references/testing-and-debugging.md when writing deterministic tests with TestModel, FunctionModel, Agent.override, capture_run_messages, usage limits, or diagnosing common runtime failures.
• Run scripts/agent_smoke.py when you need a safe, no-network import/construction/run smoke check for the installed Pydantic AI package.

Core Routing

• Build agents with Agent(model, instructions=..., deps_type=..., output_type=...); prefer instructions over system_prompt unless previous system prompts must be retained in message_history.
• Use RunContext[Deps] only as the first parameter for dynamic instructions, system prompts, tools, output validators, and history processors that need runtime context.
• Use run() for async full results, run_sync() for synchronous callers, run_stream() for final-output streaming, run_stream_events() for all raw model/tool events, and iter() for graph-node control.
• Use message_history=result.new_messages() or result.all_messages() to continue a conversation; route deep message serialization, trimming, and output-tool handoff details to ../outputs-and-messages/SKILL.md.
• Use Agent.from_spec(), Agent.from_file(), or the spec= run/override parameter when agent configuration is declarative YAML/JSON/dict.
• Use TestModel, FunctionModel, models.ALLOW_MODEL_REQUESTS = False, and Agent.override(...) for tests; never rely on live provider credentials for unit tests.

Boundaries

• For function tools, tool schemas, toolsets, approvals, deferred tools, and tool search, read ../tools-and-toolsets/SKILL.md.
• For structured output modes, output functions, message-part serialization, multimodal inputs, and final-output handoff history, read ../outputs-and-messages/SKILL.md.
• For provider-prefixed model strings, optional provider extras, model settings depth, wrappers, native provider tools, and embeddings, read ../models-and-providers/SKILL.md.
• For MCP, capabilities/hooks depth, durable execution, Logfire, A2A, and UI adapters beyond core agent methods, read ../mcp-and-integrations/SKILL.md.
• For Agent.to_cli(), Agent.to_web(), pai, clai, and application entry points, read ../cli-and-apps/SKILL.md.

Non-Negotiables

• Keep examples deterministic unless explicitly writing production provider code; use provider-prefixed model strings such as openai:gpt-5.2 only where live provider access is intentional.
• Do not use deprecated split retry kwargs (tool_retries, output_retries) in new code; use retries={'tools': N, 'output': M} at construction and retries={'output': N} per run.
• Do not add legacy history_processors= in new agents; use capabilities=[ProcessHistory(...)] for history processing and route advanced capability design to mcp-and-integrations.
• Do not assume run_stream() executes tool calls after an early final-looking text/output; use run_stream_events() or iter() when every tool event matters.