prompting

---
social:
  title: Prompting Agents
  tagline: Send structured prompts, files, and resource content to agents.
  description: Send structured prompts, files, and resource content to agents.
  alt: fast-agent social card — Prompting Agents
---

# Prompting Agents

**fast-agent** provides a flexible MCP based API for sending messages to agents, with convenience methods for handling Files, Prompts and Resources.

Read more about the use of MCP types in **fast-agent** in the
[MCP overview](../mcp/#integration-with-mcp-types).

## Sending Messages

The simplest way of sending a message to an agent is the `send` method:

```python
response: str = await agent.send("how are you?")
```

This returns the text of the agent's response as a string, making it ideal for simple interactions.

You can attach files by using `Prompt.user()` method to construct your message:

```python
from fast_agent import Prompt
from pathlib import Path

plans: str = await agent.send(Prompt.user("Summarise this PDF", Path("secret-plans.pdf")))
```

`Prompt.user()` automatically converts content to the appropriate MCP Type. For example, `image/png` becomes `ImageContent` and `application/pdf` becomes an EmbeddedResource.

You can also use MCP Types directly - for example:

```python
from mcp_types import ImageContent, TextContent

mcp_text: TextContent = TextContent(type="text", text="Analyse this image.")
mcp_image: ImageContent = ImageContent(type="image", mime_type="image/png", data=base_64_encoded)

response: str = await agent.send(Prompt.user(mcp_text, mcp_image))
```

> Note: use `Prompt.assistant()` to produce messages for the `assistant` role.

### Using `generate()` and multipart content

The `generate()` method allows you to access multimodal content from an agent, or its Tool Calls as well as send conversational pairs.

```python
from fast_agent import FastAgent, Prompt, PromptMessageExtended

message = Prompt.user("Describe an image of a sunset")

response: PromptMessageExtended = await agent.generate([message])

print(response.last_text())  # Main text response
```

The key difference between `send()` and `generate()` is that `generate()` returns a `PromptMessageExtended` object, giving you access to the complete response structure:

- `last_text()`: Gets the last text response - usually the Assistant message without Tool Call/Response information.
- `first_text()`: Gets the first text content if multiple text blocks exist
- `all_text()`: Combines all text content in the response - including Tool Call/Response information.
- `content`: Direct access to the full list of content parts, including Images and EmbeddedResources

This is particularly useful when working with multimodal responses or tool outputs:

```python
# Generate a response that might include multiple content types
response = await agent.generate([Prompt.user("Analyze this image", Path("chart.png"))])

for content in response.content:
    if content.type == "text":
        print("Text response:", content.text[:100], "...")
    elif content.type == "image":
        print("Image content:", content.mime_type)
    elif content.type == "resource":
        print("Resource:", content.resource.uri)
```

You can also use `generate()` for multi-turn conversations by passing multiple messages:

```python
messages = [
    Prompt.user("What is the capital of France?"),
    Prompt.assistant("The capital of France is Paris."),
    Prompt.user("And what is its population?"),
]

response = await agent.generate(messages)
```

The `generate()` method provides the foundation for working with content returned by the LLM, and MCP Tool, Prompt and Resource calls.

### Using `structured()` for typed responses

When you need the agent to return data in a specific format, use the `structured()` method. This parses the agent's response into a Pydantic model:

```python
from pydantic import BaseModel
from typing import List


# Define your expected response structure
class CityInfo(BaseModel):
    name: str
    country: str
    population: int
    landmarks: List[str]


# Request structured information
result, message = await agent.structured([Prompt.user("Tell me about Paris")], CityInfo)

# Now you have strongly typed data
if result:
    print(f"City: {result.name}, Population: {result.population:,}")
    for landmark in result.landmarks:
        print(f"- {landmark}")
```

The `structured()` method returns a tuple containing:
1. The parsed Pydantic model instance (or `None` if parsing failed)
2. The full `PromptMessageExtended` response

This approach is ideal for:
- Extracting specific data points in a consistent format
- Building workflows where agents need structured inputs/outputs
- Integrating agent responses with typed systems

Always check if the first value is `None` to handle cases where the response couldn't be parsed into your model:

```python
result, message = await agent.structured([Prompt.user("Describe Paris")], CityInfo)

if result is None:
    # Fall back to the text response
    print("Could not parse structured data, raw response:")
    print(message.last_text())
```

The `structured()` method provides the same request parameter options as `generate()`.

!!! note

    LLMs produce JSON when producing Structured responses, which can conflict with Tool Calls. Use a `chain` to combine Tool Calls with Structured Outputs. 



## MCP Prompts

Apply a Prompt from an MCP Server to the agent with:

```python
response: str = await agent.apply_prompt("setup_sizing", arguments={"units": "metric"})
```

You can list and get Prompts from attached MCP Servers:

```python
from mcp_types import GetPromptResult, PromptMessage

prompt: GetPromptResult = await agent.get_prompt("setup_sizing")
first_message: PromptMessage = prompt.messages[0]
```

and send the native MCP `PromptMessage` to the agent with:

```python
response: str = await agent.send(first_message)
```

> If the last message in the conversation is from the `assistant`, it is returned as the response.

## MCP Resources

`Prompt.user` also works with MCP Resources:

```python
from mcp_types import ReadResourceResult

resource: ReadResourceResult = await agent.get_resource(
    "resource://images/cat.png", "mcp_server_name"
)
response: str = await agent.send(Prompt.user("What is in this image?", resource))
```

Alternatively, use the _with_resource_ convenience method:

```python
response: str = await agent.with_resource(
    "What is in this image?",
    "resource://images/cat.png",
    "mcp_server_name",
)
```

## Prompt Files

Long prompts can be stored in text files, and loaded with the `load_prompt` utility:

```python
from fast_agent import PromptMessageExtended, load_prompt
from pathlib import Path

prompt: list[PromptMessageExtended] = load_prompt(Path("two_cities.txt"))
result: str = await agent.send(prompt[0])
```

```markdown title="two_cities.txt"
### The Period

It was the best of times, it was the worst of times, it was the age of
wisdom, it was the age of foolishness, it was the epoch of belief, it was
the epoch of incredulity, ...
```

Prompts files can contain conversations to aid in-context learning or allow you to replay conversations with the Playback LLM:

```markdown title="sizing_conversation.txt"
---USER
the moon
---ASSISTANT
object: MOON
size: 3,474.8
units: KM
---USER
the earth
---ASSISTANT
object: EARTH
size: 12,742
units: KM
---USER
how big is a tiger?
---ASSISTANT
object: TIGER
size: 1.2
units: M
```

Multiple messages (conversations) can be applied with the `generate()` method:

```python
from fast_agent import PromptMessageExtended, load_prompt
from pathlib import Path

prompt: list[PromptMessageExtended] = load_prompt(Path("sizing_conversation.txt"))
result: PromptMessageExtended = await agent.generate(prompt)
```

Conversation files can also be used to include resources:

```markdown title="prompt_secret_plans.txt"
---USER
Please review the following documents:
---RESOURCE
secret_plan.pdf
---RESOURCE
repomix.xml
---ASSISTANT
Thank you for those documents, the PDF contains secret plans, and some
source code was attached to achieve those plans. Can I help further?
```

```python
from fast_agent import PromptMessageExtended, load_prompt
from pathlib import Path

prompt: list[PromptMessageExtended] = load_prompt(Path("prompt_secret_plans.txt"))
result: PromptMessageExtended = await agent.generate(prompt)
```

!!! Note "File Format / MCP Serialization"

    If the filetype is `json`, fast-agent saves a `{"messages": [...]}` JSON container. It can contain either MCP `PromptMessage` objects (legacy) or `PromptMessageExtended` objects (preserves tool calls, channels, etc). `fast_agent.load_prompt` loads either the text or JSON format directly.
    See [History Saving](../models/#history-saving) to learn how to save a conversation to a file for editing or playback.


### Using an external MCP prompt server

Use `fast_agent.load_prompt` when your application owns prompt files. To expose prompts or resources through MCP, configure an external MCP server according to that server's installation instructions:

```yaml title="fast-agent.yaml"
mcp:
  servers:
    prompts:
      command: "uvx"
      args: ["your-mcp-server-package"]
```

The external server defines its available MCP prompts and resources. Prompt arguments are server-specific.