feat: add dynamic instructions from ResourceProviders for context…

[Million-mo]

…-aware prompts

Add runtime_checkable instruction function types supporting 4 context patterns:
- No context, AgentContext, RunContext, or both contexts
- Both sync and async variants Add context wrapping utility to adapt instruction functions for PydanticAI. Extend ResourceProvider with get_instructions() method returning list[InstructionFunc]. Add ProviderInstructionConfig for YAML-based configuration:
- type: provider with ref or import_path
- Mutual exclusion validation Integrate with NativeAgent:
- Collect and wrap instructions from providers in get_agentlet()
- Pass to PydanticAgent constructor
- Fail-safe error handling Add comprehensive documentation and 45+ tests.

---

备份迁移自 SRC-PR#1 · 作者 @Leoyzen · 创建于 2026-02-08T15:58:41Z · head=feature/dynamic-instruction-for-provider base=main
源状态: closed

[Million-mo]

评论 by @gemini-code-assist[bot] 于 2026-02-08T15:59:09Z（备份迁移）

Summary of Changes

Hello @Leoyzen, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the agent's ability to generate highly dynamic and context-aware prompts. By allowing ResourceProviders to contribute instructions that are re-evaluated at runtime, agents can now adapt their behavior more intelligently based on the current AgentContext and RunContext. This moves beyond static system prompts, enabling more flexible and responsive agent interactions without altering core agent logic.

Highlights

• Dynamic Instructions from ResourceProviders: Introduced a new feature allowing ResourceProviders to supply dynamic instructions that are re-evaluated on each agent run, providing context-aware prompts.
• Flexible Context Patterns: Instruction functions now support four context patterns: no context, AgentContext only, RunContext only, or both contexts, with support for both synchronous and asynchronous variants.
• PydanticAI Integration and Wrapping Utility: Added a utility (wrap_instruction) to adapt instruction functions for compatibility with PydanticAI, automatically injecting the correct context based on function signatures.
• YAML Configuration for Instructions: Implemented ProviderInstructionConfig for YAML-based configuration of dynamic instructions, allowing reference to existing providers or import paths.
• NativeAgent Integration and Error Handling: Integrated dynamic instruction collection and wrapping into NativeAgent's get_agentlet() method, including fail-safe error handling for instruction function failures.
• Comprehensive Documentation and Testing: Added extensive documentation covering the new feature, its configuration, and usage, alongside over 45 new tests to ensure robustness and correctness.

Changelog

• docs/advanced/system-prompts.md
  • Added a new section 'Provider-Based Dynamic Instructions' detailing how ResourceProviders can supply dynamic, context-aware instructions.
  • Detailed the four types of instruction function contexts: No context, AgentContext, RunContext, and both.
  • Included a comparison table between Function-Generated and Provider-Based Instructions.
  • Described the order of instruction processing and error handling for failed instruction functions.
  • Added tips on when to use Provider-Based Instructions.
• docs/configuration/resources.md
  • Added a new section 'Dynamic Instructions from Resource Providers' explaining the concept and how it works.
  • Provided Python and YAML examples for implementing and configuring instruction providers.
  • Listed benefits of dynamic instructions and described error handling.
• docs/examples/mcp_sampling_elicitation/demo.py
  • Minor reordering of imports (anyio).
• src/agentpool/agents/native_agent/agent.py
  • Removed unused imports (RunContext from pydantic_ai, ToolDefinition, get_argument_key).
  • Imported wrap_instruction utility.
  • Modified get_agentlet to collect and wrap instructions from all resource providers.
  • Added logic to append the formatted system prompt as a static instruction.
  • Implemented error handling for get_instructions() calls on providers and for wrapping individual instruction functions.
  • Refactored tool wrapping logic to use tool.to_pydantic_ai(function_override=wrapped).
  • Removed old tool registration logic.
• src/agentpool/docs/gen_examples.py
  • Minor formatting change (added a blank line).
• src/agentpool/docs/utils.py
  • Minor reordering of imports (types).
  • Updated _strip_docstring_sections to use a tuple for startswith check.
  • Changed generate_tool_docs to use a generator expression for lines.extend.
• src/agentpool/prompts/instructions.py
  • New file: Introduced InstructionFunc union type for various instruction function signatures.
  • Defined SimpleInstruction, AgentContextInstruction, RunContextInstruction, and BothContextsInstruction protocols using @runtime_checkable.
  • Added InstructionMetadata class for optional instruction function metadata.
• src/agentpool/resource_providers/base.py
  • Added InstructionFunc to TYPE_CHECKING imports.
  • Introduced an asynchronous get_instructions() method to the ResourceProvider base class, returning an empty list by default.
• src/agentpool/resource_providers/instruction_provider.py
  • New file: Created InstructionProvider class to wrap ProviderInstructionConfig.
  • Handles resolving instruction functions from either a referenced provider or an imported provider class.
  • Delegates get_instructions() calls to the underlying provider.
• src/agentpool/tools/base.py
  • Modified to_pydantic_ai method to accept an optional function_override argument, allowing external wrapping of the tool's callable.
• src/agentpool/utils/context_wrapping.py
  • New file: Introduced wrap_instruction utility function.
  • This function adapts instruction functions to pydantic-ai's (RunContext) -> str signature.
  • Automatically detects and injects AgentContext and/or RunContext based on the function's signature.
  • Includes error handling with a configurable fallback string.
• src/agentpool_config/instructions.py
  • New file: Defined ProviderInstructionConfig Pydantic model for YAML-based configuration of dynamic instructions.
  • Includes fields for ref (reference to existing provider) and import_path (path to provider class).
  • Added validation to ensure exactly one of ref or import_path is provided.
• tests/agents/native_agent/init.py
  • New file: Added package __init__.py for test module.
• tests/agents/native_agent/test_agent_instructions.py
  • New file: Added comprehensive tests for NativeAgent's integration with dynamic instructions.
  • Tests cover collection, wrapping, and evaluation of instructions from various provider types (simple, AgentContext-aware, RunContext-aware).
  • Includes tests for error handling and configuration via ProviderInstructionConfig.
• tests/config/init.py
  • New file: Added package __init__.py for test module.
• tests/config/test_instructions_config.py
  • New file: Tests for ProviderInstructionConfig model, including valid configurations and validation errors.
• tests/prompts/test_instructions_types.py
  • New file: Tests for the new instruction function protocols (SimpleInstruction, AgentContextInstruction, RunContextInstruction, BothContextsInstruction) and the InstructionFunc union type.
  • Includes tests for InstructionMetadata and @runtime_checkable behavior.
• tests/resource_providers/test_base.py
  • New file: Tests for the new get_instructions method on the ResourceProvider base class, verifying its existence, async nature, and default return value.
• tests/utils/test_context_wrapping.py
  • New file: Tests for the wrap_instruction utility, covering various function signatures (sync/async, different context types), error handling, and preservation of function metadata.

Activity

• Leoyzen created this pull request to introduce dynamic instructions for context-aware prompts.
• The pull request includes the addition of several new files defining instruction types, configuration models, and utility functions for context wrapping.
• Existing core agent logic in native_agent/agent.py has been modified to integrate the new dynamic instruction system.
• New documentation has been added to docs/advanced/system-prompts.md and docs/configuration/resources.md to explain the feature.
• A substantial number of new tests have been added across multiple test modules to validate the new functionality and ensure its robustness.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[Million-mo]

评论 by @Leoyzen 于 2026-02-09T01:43:15Z（备份迁移）

/gemini review