Load system_prompt with decorator using AGUIAdapter

[dav04]

Initial Checks

• I confirm that I'm using the latest version of Pydantic AI
• I confirm that I searched for my issue in https://github.com/pydantic/pydantic-ai/issues before opening this issue

Description

Following this example to implement the AG-UI protocol:

agent = Agent('openai:gpt-5')

app = FastAPI()


@app.post('/')
async def run_agent(request: Request) -> Response:
    accept = request.headers.get('accept', SSE_CONTENT_TYPE)
    try:
        run_input = AGUIAdapter.build_run_input(await request.body())  # 
    except ValidationError as e:
        return Response(
            content=json.dumps(e.json()),
            media_type='application/json',
            status_code=HTTPStatus.UNPROCESSABLE_ENTITY,
        )

    adapter = AGUIAdapter(agent=agent, run_input=run_input, accept=accept)
    event_stream = adapter.run_stream() # 

    sse_event_stream = adapter.encode_stream(event_stream)
    return StreamingResponse(sse_event_stream, media_type=accept)

If I pass system_prompt directly to the agent or if I use the decorator like this, the agent is executed without the system_prompt:

@agent.system_prompt
def get_agent_instructions(ctx: RunContext[str]) -> str:
    print('----LOADING PROMPT----')  # this is not printed
    return 'Be fun!'

Instead if I use the instructions parameter, agent return a compliant response with the prompt.

Is it possible that AGUIAdapter does not consider system_prompt parameter during execution?

Thanks.

[maroshii]

I can confirm this is happening for the VercelAIAdapter as well using pydantic-ai>=1.9.1

[DouweM]

This is expected behavior per https://ai.pydantic.dev/agents/#instructions, although it could be explained more clearly and may warrant an explicit callout in the UI/AG-UI/VercelAI docs. The context is that system_prompt is ignored when message_history is provided (like the messages that the frontend passes in) because the system prompt is expected to already be in the history. instructions on the other hand are always included.

Is it an option for you to use @agent.instructions instead?

[dav04]

Actually this behaviour is happening also with the first message, where message history is an empty list.

With instructions always included, is there the risk that I pay multiple times with a long prompt for the same tokens? System prompt is at the beginning and tokens are calculated only one time.
Usually I prefer instructions because they reduce errors on response, while system prompt loses his strength if conversation has too much messages.

[DouweM]

Actually this behaviour is happening also with the first message, where message history is an empty list.

@dav04 Are you sure? That shouldn't be happening. Wouldn't the frontend also pass the first message as a messages list with a single item?

With instructions always included, is there the risk that I pay multiple times with a long prompt for the same tokens? System prompt is at the beginning and tokens are calculated only one time. Usually I prefer instructions because they reduce errors on response, while system prompt loses his strength if conversation has too much messages.

With providers that natively support instructions, like OpenAI, that shouldn't be an issue as they specifically introduced instructions as an alternative to the system_prompt history part so that it can be changed during a run without changing the prefix of the entire message history. So I imagine they have some clever solution to that. The docs hint that they do:

When using along with previous_response_id [in other words: when continuing with a history from a previous run], the instructions from a previous response will not be carried over to the next response. This makes it simple to swap out system (or developer) messages in new responses.

With providers that don't natively support instructions, we insert them as a system part at the start of the message history, so the prompt prefix would indeed change.

[dav04]

@dav04 Are you sure? That shouldn't be happening. Wouldn't the frontend also pass the first message as a messages list with a single item?

I'm sure because I get message_history from the DB, not from the frontend, so the first message is not in the DB yet.
I'm doing this because in this way I can pass only essential information instead of data that increase number of tokens per request.

With providers that natively support instructions

I have to use Vertex and Google talks only about system instructions.

[DouweM]

I'm sure because I get message_history from the DB, not from the frontend, so the first message is not in the DB yet.

@dav04 Can you help me reproduce this? The following script works as expected:

from pprint import pprint

from pydantic_ai import Agent, RunContext

agent = Agent('test', deps_type=str)


@agent.system_prompt
def get_agent_instructions(ctx: RunContext[str]) -> str:
    print('----LOADING PROMPT----')  # this is not printed
    return 'Be fun!'


result = agent.run_sync('Hello, world!', message_history=[], deps='foo')
pprint(result.all_messages())

Output:

----LOADING PROMPT----
[ModelRequest(parts=[SystemPromptPart(content='Be fun!', timestamp=datetime.datetime(2025, 11, 4, 0, 4, 24, 913587, tzinfo=datetime.timezone.utc)), UserPromptPart(content='Hello, world!', timestamp=datetime.datetime(2025, 11, 4, 0, 4, 24, 913610, tzinfo=datetime.timezone.utc))]),
 ModelResponse(parts=[TextPart(content='success (no tool calls)')], usage=RequestUsage(input_tokens=54, output_tokens=4), model_name='test', timestamp=datetime.datetime(2025, 11, 4, 0, 4, 24, 914547, tzinfo=datetime.timezone.utc))]

I have to use Vertex and Google talks only about system instructions.

That system_instruction is a dedicated field on the API though, not a part in the message history, so similar to OpenAI I wonder if they treat it more intelligently when it comes to message history (prefix) caching.

[dav04]

@DouweM your example is the normal case and it works perfectly.

In my case I'm using the AGUIAdapter, like this:

import json
from http import HTTPStatus

from fastapi import FastAPI
from fastapi.requests import Request
from fastapi.responses import Response, StreamingResponse
from pydantic import ValidationError

from pydantic_ai import Agent
from pydantic_ai.ui import SSE_CONTENT_TYPE
from pydantic_ai.ui.ag_ui import AGUIAdapter


agent = Agent('openai:gpt-5', deps_type=str)

app = FastAPI()

@agent.system_prompt
def get_agent_instructions(ctx: RunContext[str]) -> str:
    print('----LOADING PROMPT----')  # this is not printed
    return 'Be fun!'

@app.post('/')
async def run_agent(request: Request) -> Response:
    accept = request.headers.get('accept', SSE_CONTENT_TYPE)
    try:
        run_input = AGUIAdapter.build_run_input(await request.body())
    except ValidationError as e:
        return Response(
            content=json.dumps(e.json()),
            media_type='application/json',
            status_code=HTTPStatus.UNPROCESSABLE_ENTITY,
        )

    adapter = AGUIAdapter(agent=agent, run_input=run_input, accept=accept)
    event_stream = adapter.run_stream(
        message_history=[],
        deps='foo'
    )

    sse_event_stream = adapter.encode_stream(event_stream)
    return StreamingResponse(sse_event_stream, media_type=accept)

[DouweM]

@dav04 Ok so in this case the explicit message_history is prepended to run_input.messages, which is perhaps surprising. So the agent would be run with the history from the frontend anyway. If you want to send no message history at all, you can clear run_input.messages, but then you'll get an error that no history or new user prompt is provided and there's thus nothing to send to the LLM.

[dav04]

So, having run_input.messages with only the user prompt, the agent don't append the system prompt because it finds already a message history; instead instructions are always appended and they works.
So, to use system prompt the only way is to append it from the frontend, right?

Since we're talking about AGUIAdapter and the endpoint has to stream events, is it not possible to get also the model response attributes like token usage?

[DouweM]

So, having run_input.messages with only the user prompt, the agent don't append the system prompt because it finds already a message history; instead instructions are always appended and they works. So, to use system prompt the only way is to append it from the frontend, right?

You could build your own ModelRequest with a SystemPromptPart and pass it in via message_history so that it's prepended (or equivalently: modify RunInput.messages), but of course that's not nearly as convenient as the built-in agent system_prompt feature.

Since we're talking about AGUIAdapter and the endpoint has to stream events, is it not possible to get also the model response attributes like token usage?

You can! AGUIAdapter.run_stream and the other methods have an on_complete handler than is passed the AgentRunResult that has a usage() method among other things.

[dav04]

@DouweM thanks for your support, now it's more clear!