Support injecting server instructions into the system prompt

[chughtapan]

I recently learned that the MCP protocol supports injecting system instructions into the agent's context. The use-case is when there are shared instructions for the agent on how to choose amongst the various tools, provide common setups, etc.

References:

• Add support System Message injection by the MCP Servers for instruction injection and state exposure. modelcontextprotocol/modelcontextprotocol#148
• https://github.com/jlowin/fastmcp/blob/13dd2bfa0ccc5e6904a26d3f231eceebf45515cd/src/fastmcp/server/server.py#L283

Incorporating these instructions into the server prompt should not be necessary with fast-agent but should definitely be available as an option? I'm happy to put in the work for doing this, since this is being a blocker for one of my projects.

Curious what others here think?

[evalstate]

This is top of the TODO list: if you are willing to do a PR I'd be super grateful. I did have an earlier version of this.

Ideally, we'd be able to specify in the fastagent config file whether the instructions should be ignored, specified directly in the yaml file, or inserted automatically (the default). The other useful thing would be to allow the inclusion of a template {{date}} in the instructions for Agent/System prompts that want to reference the current date.

Just as an FYI for reference -- if you look at base_agent.py (

fast-agent/src/mcp_agent/agents/base_agent.py

Lines 655 to 667 in 8d5823c

	return AgentCard(
	name=self.name,
	description=self.instruction,
	url=f"fast-agent://agents/{self.name}/",
	version="0.1",
	capabilities=DEFAULT_CAPABILITIES,
	defaultInputModes=["text/plain"],
	defaultOutputModes=["text/plain"],
	provider=None,
	documentationUrl=None,
	authentication=None,
	skills=skills,
	)

) you will see that the instruction is used when generating an A2A agent card - which in turn is used by router_agent.py and likely in more places in the future. I think that's a good thing right now: small agents described by their attached servers/capabilities are a good default.

[evalstate]

Also to add - this feature was going to be built alongside an improved Server connection display showing advertised capabilities from both so instruction deployment would be included in that.

[chughtapan]

Thanks for the update! I have come up with the following workaround for now:

• The agent's instructions tell it use a specific tool e.g., list_instructions before using any tools
• Use a thin FastMCP proxy which captures the instructions from a server and exposes them using the list_instructions tool
• The agent then connects to this proxy and continues.

Not a perfect solution: the instructions end up in user messages rather than system messages, but I think it's enough to unblock me for now. If I run into roadblocks again, I'll probably start looking into fixing this properly here.

[jdecker76]

I know this is a little old, but wanted to share how we handle system prompt injection in our agents. It works very well for us. It takes advantage of two things:

• fast agent implements dunder methods for getitem and setitem. We use this to associate a "ResourceConfig" with an agent (we have a ResourceManager class with helpers for this, as well as for injecting the resources into the system prompt)
• we use the _llm variable directly for setting the instruction. (I think I may do a PR soon with an actual getter)

Here is the ResourceManager we use:

import json
from typing import Dict, List, Set, TypedDict, Optional
from pydantic import BaseModel
from agents.fast_agent import fast_agent
from mcp_agent.agents.agent import Agent
from mcp_agent.core.agent_app import AgentApp
from mcp.types import TextResourceContents
from utils.generic_cache import cached

"""
Note: TextResourceContents objects:
[
    TextResourceContents(
        uri=AnyUrl('claims://employee/info/auth0|65d8b20937ceba3f2b1c712c'), 
        mimeType='text/plain', 
        meta=None, 
        text='{
            "id": 1234,
            "auth0Id": "auth0|xxxxxxxxxxxxxxxxxx",
            "email": "someone@acuservecorp.com",
            "employeeFirstName": "John",
            "employeeLastName": "Doe"
        }'
    )
]
""" 



Agt = Agent | str  # Wrapper for a True Fast Agent agent, or the string name of the agent.  

class ResourceConfig(TypedDict):
    uri: str
    server: str
    description: str

class ResourceContent(TypedDict):
    uri: str
    content: str
    description: str

class Resource(BaseModel):
    uri: str
    mimeType: str  
    meta: Optional[dict] = None
    text: str
    description: str
    
    @classmethod
    def from_text_resource(cls, text_resource: TextResourceContents, description: str):
        return cls(
            uri=str(text_resource.uri),
            mimeType=text_resource.mimeType,
            meta=text_resource.meta,
            text=text_resource.text,
            description=description
        )


class ResourceManager:
    """
    ResourceManager is a utility class for managing MCP Resources.
    This includes associating resource configs with Fast Agent Agents and fetching resources from MCP servers.
    """
    def __init__(self, fa_app: AgentApp):
        self.fa_app = fa_app

    def _to_agent(self, agent: Agt) -> Agent:
        """
        Agt->Agent conversion.

        This is a convenience method that allows agents to be specified as a string name or an Agent instance.
        """
        if isinstance(agent, str):
            return self.fa_app.agents[agent]
        return agent

    def associate_configs(self, agent: Agt, configs: List[ResourceConfig]) -> None:
        """
        Associates a list of ResourceConfig objects with an agent.
        
        These resources can be automatically injected into the agent's system prompt during startup using the inject_system_resources function.
        Template URIs are supported using Python format string syntax (e.g., "claims://customer/active/{auth0_id}").
        
        Args:
            agent: The FastAgent agent instance or the string name of the agent
            resource_config_list: List of resource dictionaries, each containing:
                - uri: Resource URI (supports templates like "claims://endpoint/{param}")
                - server: Name of the MCP server hosting the resource
                - description: Human-readable description of the resources
                
        Example:
            set_agent_instruction_resources("my-agent", [
                {"uri": "claims://customer/active/{auth0_id}", "server": "claims-api", "description": "Active customers"}
            ])
        """
        agent = self._to_agent(agent)
        agent["resource_configs"] = configs

    def get_associated_configs(self, agent: Agt, template_params: Dict[str, str] | None = None) -> List[ResourceConfig]:
        """
        Gets the resource config list for a specific agent and optionally fills in template parameters.
        
        Args:
            agent: The FastAgent agent instance
            template_params: Optional dictionary of parameters to substitute in URI templates.
                            Keys should match template variables in URI strings (e.g., {"auth0_id": "auth0|123..."})
            
        Returns:
            A @ResourceConfigList. If template_params provided, URIs will have template variables filled in.
            Returns empty list if agent doesn't exist or doesn't have instruction_resources configured.
            
        """
        agent = self._to_agent(agent)
        # Gracefully handle missing agent or missing instruction_resources
        resource_configs = agent.get("resource_configs", [])
        
        if not resource_configs or template_params is None:
            return resource_configs
        
        # Fill in template parameters
        filled_resource_configs = []
        for resource_config in resource_configs:
            filled_resource_config = resource_config.copy()
            try:
                filled_resource_config["uri"] = resource_config["uri"].format(**template_params)
                filled_resource_configs.append(filled_resource_config)
            except KeyError as e:
                # Template resource with missing parameter - this is a configuration error!
                raise KeyError(f"Missing required template parameter {e} for resource URI: {resource_config['uri']}")
        
        return filled_resource_configs
    
    @cached(ttl_seconds=300, max_size=500, group="resource_manager" )  # 5 minute cache, 500 entries max
    async def get_resources(self, resource_configs: List[ResourceConfig]) -> List[Resource]:
        """
        Fetches a list of MCP resources from the MCP server from a ResourceConfigList.
        Results are automatically cached for 5 minutes to improve performance.
        Different resource configs will have separate cache entries.

        arg resource_config_list: List of ResourceConfig obects

        return: List[Resource]
        """
        loaded_resources: List[Resource] = []

        for resource_config in resource_configs:
            # fetch the resource from the MCP server
            response_list: List[TextResourceContents] = await self.fa_app.get_resource(resource_config['uri'], resource_config['server'])
            
            # Process each TextResourceContents in the list
            for single_resource in response_list:
                # parse the resource content as JSON if it is a string
                try:
                    parsed_content = json.loads(single_resource.text)
                except json.JSONDecodeError:
                    parsed_content = single_resource.text

                # convert from TextResourceContents to Resource
                loaded_resource = Resource.from_text_resource(single_resource, resource_config['description'])
                loaded_resource.text = parsed_content

                # add the resource to the list
                loaded_resources.append(loaded_resource)

        return loaded_resources
    
    async def inject_system_prompt(self, agent: Agt, resources: List[Resource], private: bool) -> bool:
        """
        Injects a list of resources into the agent llm's system prompt. This is useful for setting or restoring
        the system prompt to a known state.

        Args:
            agent: The FastAgent agent instance or the string name of the agent
            resources: A list of Resource objects.
            private: Whether to mark the resources as private/confidential in the instruction

        returns: True if the resources were injected successfully, False otherwise.
        """
        # Create a context message with all the injected resources
        privacy: str = "not private and can be shared" if not private else "private and should not be shared"
        context_parts: List[str] = [f"Use the following resources to answer user questions.  These are {privacy}.\n"]
        
        
        for resource in resources:
            context_parts.append(f"## {resource.description}")
            context_parts.append(f"Source: {resource.uri}")
            context_parts.append(f"Content: {resource.text}")
            context_parts.append("")  # Add spacing
        
        # Create system message with the context information
        context = "\n".join(context_parts)
        augmented_instructions: str = f"{agent.instruction}\n\n{context}"
        
        if agent._llm:
            agent._llm.instruction = augmented_instructions
            return True
        return False
    
# Instantiate a global resource manager for all agents to use
resource_manager = ResourceManager(fast_agent)

Here is a simple example of how we define an agent with the ResourceConfig for system prompt injection:

from agents.fast_agent import fast_agent
from utils.resource_manager import resource_manager

agent_name = "test-agent"

@fast_agent.agent(
    name=agent_name,
    model=BedrockModel.US_AMAZON_NOVA_PRO_V1_0.value,
    instruction="""You are a test agent... """,
    servers=["test-server"],
)
async def test_agent():
    pass 

# Associate a ResourceConfig with the agent.  We will fetch it later for system prompt injection
resource_manager.associate_configs(agent_name, [
    {"uri": "test://path/to/{auth0_id}", "server": "test-server", "description": "Authorized customers for this user"}
])

Then in our app, this is how we 1) inject the agent's associated resources (set up with the ResourceManager) and 2) Add any other resourceConfigs as well.

 # get the agent-specific instruction resources:
    agent_instruction_resources = resource_manager.get_associated_configs("test-agent", {"id": id}) # template expansion
    # add the system-level instruction resources (not typically agent-specific)
    system_instruction_resources = [
        {"uri": f"user://info/{id}", "server": "test-server", "description": "Employee information"},
        {"uri": "utils://date", "server": "test-server", "description": "Current date"},
    ]
    resources_to_inject = agent_instruction_resources + system_instruction_resources

    # Inject the resources into the system prompt
    resource_manager.inject_system_prompt("ar-guidelines", resources_to_inject, private=False)
    
    await agent.interactive(agent_name=agent_name)

While not a perfect solution, it has worked well for us

[evalstate]

That's really nice @jdecker76 thanks for sharing.

I think for instructions specifically, we should build on the existing system prompt variable resolution (like {{currentDate}} or {{urls}}). Then we can have an {{instructions}} placeholder that takes concatenated instructions from the MCP Servers.

I also wanted the ability to switch instructions off, or override them for specific servers.

[jdecker76]

I wouldn't mind doing the PR on this. Can we hash out how it should work?
How I'm currently handling it: an external manager class that associates URI's with agents. To inject, we fetch the resources, then add it to agent.instruction, and put it into agent._llm.instruction
It has worked really well. I think it just comes down to two decisions:
A) General injection (it's up to the user to supply the content to inject) - meaning if they wanted to inject resources, they would have to fetch them first
B) Automatic Resource injection by supplying a list of resource URIs to inject.

• New parameter for Agent decorator? Auto inject if the parameter is present?
• Should we have a {resources} template variable for control over where it gets injected, or just append to the end?

I like the thought of auto-resource injection from a list of URIs, but perhaps exposing a lower level method for general injection would make sense as well. I think also in this scope, we should have a .llm getter for _llm

[chughtapan]

Closing this now as the {{serverInstructions}} is now implemented as a macro