Skip to main content

Configure an Agent: Model, System Prompt, and Tools

Choose the Agent's model and tools and learn how the Agent component works.

About This Task​

You can add MCP servers, pipelines, and custom code as tools. Make sure the tool's name and description are meaningful and help the Agent decide when to use the tool. Add instructions on how to use the tool in the Agent's prompt.

Prerequisites​

Configure the Agent​

Configure the Model and System Prompt​

  1. Drag the Agent component onto the canvas from the Component Library.
  2. Click the Model field to open the Agent configuration panel, and choose the model from the list.
  3. Enter the system prompt for the Agent.

Add an MCP Server as a Tool​

MCP Tool

The server must be a remote server. To use a local server, first deploy it to a remote server.

  1. In the Tools section of the Agent configuration panel, click Add Tool.
  2. Choose MCP Server.
  3. Choose the transport protocol supported by the MCP Server you want to connect to. You'll find this information in the MCP Server documentation.
    • Choose Server-Sent Events (SSE) to keep an open connection and receive real-time updates as they occur.
    • Choose Streamable HTTP to receive updates in chunks as they become available.
  4. Give your server a name to help you identify it later.
  5. Enter the server URL.
  6. Optionally, enter an authentication token if the server requires one.
    MCP API Key

    If you enter the MCP API key when adding the tool, it's automatically added as a workspace secret with the MCP server name.

  7. Click Connect. The MCP server details open.
MCP Server Details
  1. Set the tool call timeout. This is the maximum time in seconds the Agent will wait for a response from the MCP server.
  2. From the list of available MCP tools, choose the tools you want to expose to the Agent.
Running MCP Tools on Their own

You can run MCP tools on their own from the agent component card. Click Manage Tool next to the MCP server and choose the tool to run. Use this to debug or test tools without running the whole agent. For details, see Run Components and Pipelines in Builder

Example Configuration​

The Agent component with MCP configured

Add Custom Code as a Tool​

You can add custom Python functions as tools to your Agent. The code must use the @tool decorator that automatically converts your function into a tool. Each tool must have a name, description, and parameters. For detailed explanation of custom code as tools, see Agent Tools.

  1. In the Tools section of the Agent configuration panel, click Add Tool.
  2. Choose Code as the tool type.
  3. Enter the Python code for your tool function. The code must use the @tool decorator and must define a function that the Agent can call. Use Python's typing.Annotated to add descriptions to parameters. This helps the Agent understand what each parameter does. You can use the example code as a starting point. Your code is immediately validated so you can easily debug it before deploying the Agent.
AI assistant

You can also use the AI assistant to generate code for your custom tool. To do this, click the AI Assistant button on the tool card, write your request in the prompt, and watch how the code gets generated.

Code Component AI Assistant
  1. Add a tool name and description. Make sure the name is unique and descriptive. Make sure the description clearly explains what the tool does. The Agent uses the tool's name and description to decide when to use it.
Running Custom Tools on Their own

You can run your custom tools on their own from the agent component card. Click Manage Tool next to the tool and choose the tool to run.

Add a Pipeline as a Tool​

Use Existing Pipelines Only

For now, you can only add an existing pipeline as a tool. Make sure you have a pipeline created. and connected to an enabled index. For instructions on how to enable an index, see Enable an Index

You can add an existing Haystack Platform pipeline as a tool. Such pipeline becomes detached from the original pipeline, so any changes you make to the original pipeline don't affect the tool pipeline.

Coming soon

Editing a pipeline tool is coming soon. Bear with us while we're working on it. For now, you can create a pipeline in Builder and add it as an agent's tool.

  1. In the Tools section of the Agent configuration panel, click Add Tool.
  2. Choose Pipeline as the tool type.
  3. In the Create Pipeline Tool window:
    1. Choose an existing pipeline from the list.
    2. Choose the version of the pipeline you want to use.
    3. Enter a name and a description for the pipeline tool. Make sure they are meaningful as the agent uses them to decide when to use the tool.
    4. Click Add Pipeline Tool. The Agent configuration panel opens.
  4. Under Tools, click the Manage Tool icon next to the pipeline you just added.
  5. Choose the pipeline inputs and outputs you want to expose to the Agent:
    1. Expand Pipeline Inputs.
    2. Choose how you want the pipeline to receive its inputs:
      • Choose LLM for the agent to automatically generate the input and feed it to the pipeline.
      • Choose State to read the input from the agent's state. Input stored in state is the input that earlier components or tools generated.
    3. Expand Pipeline Outputs and choose how to handle the pipeline's outputs:
    • Choose LLM to feed the pipeline output to the agent. This is useful if the agent needs to use the pipeline output in its next turn.
    • Choose State to store the pipeline output in the agent's state. This is useful if you want the output to be available to other tools or components in the pipeline.
    • Choose Both to store the output in both the agent's state and feed it to the agent.
Running Pipeline Tools on Their own

You can run pipeline tools on their own from the agent component card. Click Manage Tool next to the pipeline tool and then choose Run.
Use this to debug or test tools without running the whole agent. For details, see Run Components and Pipelines in Builder.