Add instructions parameter

[Kludex]

Summary

We are trying to make it easier to replace system prompts when passing the message history between agents as part of the workflow. With system prompts if you pass a history, that agent system prompt will do nothing - usually what people want is to use the system prompt from that agent on the call.

This fixes only the case where you need the system prompt to be replaced between agents.

Checklist

• documentation
• tests

---

Generated by Copilot

This pull request introduces the concept of "instructions" to the Agent class and updates various parts of the codebase to support this new feature. The most important changes include the addition of new fields and methods to handle instructions, updates to the Agent class constructor, and modifications to existing functions to incorporate instructions.

New Feature: Instructions for Agents

• Addition of Instructions Fields and Methods:

  • Added instructions and instructions_functions fields to the UserPromptNode class in pydantic_ai_slim/pydantic_ai/_agent_graph.py.
  • Introduced _instructions method to prepare instructions in pydantic_ai_slim/pydantic_ai/_agent_graph.py.
  • Added instructions and instructions_functions fields to the Agent class in pydantic_ai_slim/pydantic_ai/agent.py.
  • Implemented instructions decorator method in the Agent class to register instructions functions.

• Constructor Updates:

  • Updated the Agent class constructor to accept instructions as a parameter and handle conflicts with system_prompt. [1] [2]

Codebase Modifications

• Integration of Instructions:
  • Modified various methods in pydantic_ai_slim/pydantic_ai/agent.py to include instructions in the request preparation and execution processes. [1] [2]
  • Updated example scripts and documentation in docs/agents.md, docs/api/models/function.md, docs/message-history.md, docs/models.md, and docs/tools.md to include instructions in the examples. [1] [2] [3] [4] [5] [6] [7] [8] [9] [10] [11] [12] [13] [14] [15] [16] [17]

Example Script

• New Example Script:
  • Added a new example script in main.py to demonstrate the use of instructions with the Agent class.

These changes collectively enhance the functionality of the Agent class by allowing the inclusion of instructions, providing more flexibility and control over agent behavior.

[github-actions]

Docs Preview

commit:	5a16b2c
Preview URL:	https://81fb291b-pydantic-ai-previews.pydantic.workers.dev

[hyperlint-ai]

PR Change Summary

Added the instructions parameter to various components in the documentation, enhancing the functionality and clarity of user prompts.

• Introduced the instructions parameter in multiple files to improve user prompt handling.
• Updated existing functions to include default values for the new instructions parameter.
• Modified documentation to reflect the changes in user prompt structures.

Modified Files

• docs/agents.md
• docs/api/models/function.md
• docs/message-history.md
• docs/models.md
• docs/tools.md

---

How can I customize these reviews?

Check out the Hyperlint AI Reviewer docs for more information on how to customize the review.

If you just want to ignore it on this PR, you can add the hyperlint-ignore label to the PR. Future changes won't trigger a Hyperlint review.

Note specifically for link checks, we only check the first 30 links in a file and we cache the results for several hours (for instance, if you just added a page, you might experience this). Our recommendation is to add hyperlint-ignore to the PR to ignore the link check for this PR.

[samuelcolvin]

Some models take instructions/system prompt as a message, some as a completely separate field:

separate:

• Anthropic
• Bedrock
• Gemini

As message:

• Cohere
• Grow
• Mistral
• OpenAI

Roughly 50%. Since extracting something from a list is harder than keeping it separate, then adding it, I wonder if we would be better of sending a separate field with instructions (and maybe system prompts) to the Model than adding it to messages?

[Kludex]

Things left here:

1. Should I do something else in the docs? Please review what I've added to the agent.md @dmontagu
2. What's the plan for dynamic on the system prompts?

[dmontagu]

Suggested change

They are mutually exclusive, you cannot use both in the same agent.

I guess if we do concatenation we can remove this note, but I think we should add an admonition saying basically — "For most use cases, you should use instructions. If you know what you are doing though and want to preserve system prompt messages in the message history, you can achieve that using the system_prompt argument/decorator." or similar.

[dmontagu]

We should do this whether or not there are instructions; I think it will allow us to remove the logic fork above contingent on the presence of instructions/instruction functions.