Configure an Agent: Model, System Prompt, and Tools

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. Th 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 AI Platform.

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 MCP 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 how you want to receive server updates:
- 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.

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.

Add a Component as a Tool

📘
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

📘
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.component_tool.ComponentTool. Then, define the pipeline as a component inside ComponentTool and wrap it in a SuperComponent by setting its type to haystack.core.super_component.super_component.SuperComponent.

SuperComponent 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.component_tool.ComponentTool # use the ComponentTool wrapper
        data: 
        component: # define the pipeline in the component object
            init_parameters: 
            input_mapping: 
                query:
                - query_embedder.text
                - OpenSearchBM25Retriever.query
                - ranker.query
                filters:
                - OpenSearchBM25Retriever.filters
                - OpenSearchEmbeddingRetriever.filters
            output_mapping: # here we're saying the ranker's documents output will have the label documents
                ranker.documents: documents
            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: {}
            type: haystack.core.super_component.super_component.SuperComponent # this indicates the pipeline is wrapped in a SuperComponent
        description: A tool to search travel guides, tips, and advice for specific destinations or travel topics.
        outputs_to_state: # here we're listing the outputs of the tool to be added to the Agent's state
            documents:
            source: documents
        name: travel_guide_search
        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