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

Currently, only adding MCP servers as tools is supported in the visual Builder. Use the YAML editor to add pipelines and components 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

For full Agent component documentation, see Agent.
Make sure deepset is connected to the provider of the model you want to use. The Agent works with chat models that support tool calls. For details on how to connect, see Using Hosted Models and External Services.
For instructions on how to write prompts, see Writing Prompts in deepset.

Configure the Agent

Configure the Model and System Prompt

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

Configure an MCP Server as a Tool

MCP Tool

Currently, the visual Builder only supports adding MCP servers as tools. To add other tool types, use the YAML editor.

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

In the Tools section of the Agent configuration panel, click Add Tool.
Choose MCP Server.
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.
Give your server a name to help you identify it later.
Enter the server URL.
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.
Click Connect. The MCP server details open.

Set the tool call timeout. This is the maximum time in seconds the Agent will wait for a response from the MCP server.
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

Add a Component as a Tool

info

A visual way of adding a component as a tool is coming soon.

Wrap the component with haystack.tools.component_tool.ComponentTool to make it callable. Check the component's documentation for the parameters it takes.

Close the Agent configuration panel and switch to the YAML editor.
Find the Agent in the components section.

Configure the component in the Agent's tools parameter:

- type: haystack.tools.component_tool.ComponentTool
  data:
    component:
      type: # the import path to the component, to quickly check a component type, add it to your pipeline and switch to the YAML view
      init_parameters: # configure your component, pass all init parameters here
      parameter1: value
      paramter2: value

Here's an example configuration of the SerperDevWebSearch component as a tool:

components:
  agent:
    type: haystack.components.agents.agent.Agent
    init_parameters:
      tools:
      - type: haystack.tools.component_tool.ComponentTool # this is the type you use to configure pipeline components as tools
        data: # wrap the component configuration in the data object
          component: # specify the tool type, for pipeline components, it's `component`
            type: haystack.components.websearch.serper_dev.SerperDevWebSearch # this is the component import path or type
            init_parameters: # pass the component configuration here
              api_key:
                type: env_var
                env_vars:
                - SERPERDEV_API_KEY
                strict: false
              top_k: 10
          name: web_search # give the tool a name, you can use this name as the exit condition
          description: Search the web for current information on any topic # describe what the tool does, this can help the model to decide when and if to use the tool

Add a Pipeline as a Tool

info

A visual way of adding a pipeline as a tool is coming soon.

To use a pipeline as a tool, first set its type to haystack.tools.pipeline_tool.PipelineTool.

PipelineTool runs the pipeline behind the scenes. It handles input and output mapping automatically—matching incoming arguments to the right component inputs and collecting results from the final components.

You can also explicitly configure input and output mappings:

input_mapping: Maps the Agent's input fields to specific component inputs within the pipeline used as a tool.
For example, you can indicate that the query_embedder's text input should receive the query input as follows:
```
input_mapping:
  query:
  - query_embedder.text
```
output_mapping: Specifies which outputs from the pipeline should be returned to the Agent, and under what names.
For example, this configuration returns the retriever's documents output under the label retrieved_documents. The label will be used to store the documents in the Agent's state:
```
output_mapping:
  retriever.documents: retrieved_documents
```

Close the Agent configuration panel and switch to the YAML editor.
Find the Agent in the components section.

Configure the pipeline in the Agent's tools parameter as follows:

components:
agent:
    type: haystack.components.agents.agent.Agent
    init_parameters:
    chat_generator:
    exit_conditions: ['text'] # this tells the Agent to stop once it receives text from the LLM, without tool calls
    max_agent_steps: 100
    raise_on_tool_invocation_failure: false
    streaming_callback: 
    system_prompt: |-
        You are a professional trip planner.
        You perform comprehensive research to help users plan their travels.
        Use the 'travel_guide_search' tool to find reliable information and advice about the destination.
        Use the 'weather_tool' to check the current weather forecast for the city.
        Research different aspects of the question (culture, safety, transport, events, weather).
        Use markdown to format your response.
        When you use information from the travel guide results, cite your sources using markdown links.
        It is important that you cite accurately.
    state_schema: 
        documents: 
        type: List[Document]
    tools: # define the pipeline here
    - type: haystack.tools.pipeline_tool.PipelineTool # use the PipelineTool wrapper
            data: 
        name: travel_guide_search
        description: A tool to search travel guides, tips, and advice for specific destinations or travel topics.
        input_mapping:
            query:
            - query_embedder.text
            - OpenSearchBM25Retriever.query
            - ranker.query
            filters:
            - OpenSearchBM25Retriever.filters
            - OpenSearchEmbeddingRetriever.filters
        inputs_from_state:
        is_pipeline_async: false
        output_mapping: # here we're saying the ranker's documents output will have the label documents
            ranker.documents: documents
        outputs_to_state: # here we're listing the outputs of the tool to be added to the Agent's state
            documents:
            source: documents
        outputs_to_string:
        pipeline: # this is the pipeline configuration
            components:
            query_embedder:
                init_parameters:
                model: intfloat/e5-base-v2
                truncate: END
                type: deepset_cloud_custom_nodes.embedders.nvidia.text_embedder.DeepsetNvidiaTextEmbedder
            OpenSearchBM25Retriever:
                init_parameters:
                document_store:
                    type: haystack_integrations.document_stores.opensearch.document_store.OpenSearchDocumentStore
                    init_parameters:
                    hosts:
                    index: default_index
                    embedding_dim: 768
                    return_embedding: false
                    max_chunk_bytes: 104857600
                    create_index: true
                    filters:
                fuzziness: AUTO
                top_k: 20
                type: haystack_integrations.components.retrievers.opensearch.bm25_retriever.OpenSearchBM25Retriever
            OpenSearchEmbeddingRetriever:
                init_parameters:
                document_store:
                    type: haystack_integrations.document_stores.opensearch.document_store.OpenSearchDocumentStore
                    init_parameters:
                    hosts:
                    index: default_index
                    embedding_dim: 768
                    return_embedding: false
                    max_chunk_bytes: 104857600
                    create_index: true
                    filters:
                top_k: 20
                efficient_filtering: false
                type: haystack_integrations.components.retrievers.opensearch.embedding_retriever.OpenSearchEmbeddingRetriever
                document_joiner:
            init_parameters:
                join_mode: concatenate
                type: haystack.components.joiners.document_joiner.DocumentJoiner
                ranker:
            init_parameters:
                model: intfloat/simlm-msmarco-reranker
                top_k: 2
                type: deepset_cloud_custom_nodes.rankers.nvidia.ranker.DeepsetNvidiaRanker
                connection_type_validation: true
            connections:
            - receiver: OpenSearchEmbeddingRetriever.query_embedding
                sender: query_embedder.embedding
            - receiver: document_joiner.documents
                sender: OpenSearchBM25Retriever.documents
            - receiver: document_joiner.documents
                sender: OpenSearchEmbeddingRetriever.documents
            - receiver: ranker.documents
                sender: document_joiner.documents
            max_runs_per_component: 100
            metadata: {}
        parameters: # this gives the LLM a schema of the inputs the tool expects: it must receive the query of type string, no additional properties are allowed.
            type: object
            properties:
            query:
                type: string
                description: The search query
            required:
            - query
            additionalProperties: false

Was this page helpful?

About This Task​

Prerequisites​

Configure the Agent​

Configure the Model and System Prompt​

Configure an MCP Server as a Tool​

Example Configuration​

Add a Component as a Tool​

Add a Pipeline as a Tool​