AI Agents

Integrate AI models into your workflows with the agent action

The agent action interacts with an AI model to process queries, generate content, and execute tools. It is configured with a stored LLM provider — OpenAI, Claude, Qwen, or a model router — and can be given tools that let it run workflows, delegate to other agents, run a single action, or reach an external service over MCP.

---

agent

Interacts with AI models to process queries and optionally execute tool functions.

Provider ID

The stored LLM provider instance to call.

YAML Key	providerID
Type	llm_provider
Required	Yes

An LLM is not an integration. Providers (openai, claude, qwen, and model routers) live in their own registry and are referenced by the numeric id of a stored provider instance — not by an integration name. A provider instance carries the credential, the endpoint, and the model, so pointing two agents at different models means two provider instances.

Name

Labels this agent in traces. It has no effect on what the model is asked.

YAML Key	name
Type	string
Required	No

System Prompt

Instructions that define the agent’s behavior and context. This sets the personality, constraints, and capabilities of the agent.

YAML Key	systemPrompt
Type	string
Required	No

User Prompt

The user’s message or query to send to the agent.

YAML Key	userPrompt
Type	string
Required	No

Access Memory

Gives the agent the built-in workspace file tools — read_file, write_file, and list_files — over the files in its config’s workspace, on top of whatever toolConfigs names.

YAML Key	accessMemory
Type	boolean
Required	No
Default	false

Defining your own tool called read_file replaces the built-in one rather than colliding with it.

Tool Configurations

An array of tool configurations that give the agent additional capabilities. See Tool Configuration for details.

YAML Key	toolConfigs
Type	array
Required	No

File Upload

A file to send to the model. Like download, this names where the file comes from rather than being a template string.

YAML Key	fileUpload
Type	object
Required	No

Sub-field	Description
type	request, action, or storage
identifier	The form field name, the step id, or the workspace path

Output

{{ .step_id }} holds the agent’s final reply, as text.

There is no returnLastMessage setting and no conversationID setting. The output is always the final reply, and conversation threading is owned by the run rather than configured per step.

---

Examples

Simple Query

A basic agent that answers user questions:

actions:
  ask_ai:
    type: agent
    config:
      providerID: 2
      systemPrompt: "You are a helpful assistant that provides concise answers."
      userPrompt: "{{ param \"question\" }}"

Structured Response

Generate structured data using the agent:

actions:
  analyze_sentiment:
    type: agent
    config:
      providerID: 2
      systemPrompt: |
        Analyze the sentiment of the provided text.
        Respond with a JSON object containing:
        - sentiment: "positive", "negative", or "neutral"
        - confidence: a number between 0 and 1
        - keywords: an array of relevant keywords
      userPrompt: "{{ param \"text\" }}"

Agent With Workspace Files

Let the agent read and write files in its workspace:

actions:
  research:
    type: agent
    config:
      providerID: 2
      accessMemory: true
      systemPrompt: |
        You are a research assistant. Read notes.md for prior findings,
        and append anything new you learn to it.
      userPrompt: "{{ param \"question\" }}"

---

Tool Configuration

Tools extend an agent’s capabilities by letting it perform actions during its reasoning process. There are four types: mcp, workflow, agent, and action.

Common Tool Fields

Every tool carries these, whatever its type:

Field	Description
type	mcp, workflow, agent, or action
name	The tool name the model calls. Required for workflow, agent, and action tools
description	What the tool does — this is what the model reads to decide when to use it
params	Array of parameter names the model fills in when it calls the tool

MCP Tools

Connect to external services using the Model Context Protocol (MCP). An MCP server supplies its own tool names and descriptions, so name and description are not used here.

actions:
  db_agent:
    type: agent
    config:
      providerID: 2
      systemPrompt: |
        You are a database assistant. Use the provided tools to query data.
        Never expose sensitive information like passwords.
      userPrompt: "{{ param \"query\" }}"
      toolConfigs:
        - type: mcp
          mcpConfig:
            endpoint: "https://mcp.example.com/mcp"
            toolsList:
              - query_database
              - list_tables

MCP Config Fields

Field	Description
endpoint	The MCP server endpoint URL
toolsList	Tool names to make available to the agent. Omit to offer everything the server lists
headers	Headers to send to the MCP server, for example an authorization header

Workflow Tools

Run a stored workflow when the model calls the tool. The workflow runs as its own request.

actions:
  agent_with_db:
    type: agent
    config:
      providerID: 2
      systemPrompt: "You can look up users using the provided tool."
      userPrompt: "{{ param \"query\" }}"
      toolConfigs:
        - type: workflow
          name: get_user
          description: "Get user details by ID"
          params:
            - user_id
          workflowConfig:
            id: lookup-user
            values:
              tenant: "{{ param \"tenant\" }}"

Workflow Config Fields

Field	Description
id	The config_id of the workflow to run. Required
values	Inputs the author pins, as templates resolved against the calling request. Applied after the model’s params, so a pinned value cannot be overridden by the model

Inside the workflow, read the inputs the tool passed with {{ input "user_id" }}. The workflow’s result is what the tool reports back to the model.

Agent Tools

Delegate to another agent defined in the same config. The target agent’s own userPrompt plus the model-supplied input define what it is asked, so there is no per-tool prompt.

toolConfigs:
  - type: agent
    name: summarize
    description: "Summarize a long document into three bullet points"
    params:
      - document
    agentConfig:
      id: summarizer

Agent Config Fields

Field	Description
id	The id of another agent node in the same config. Required

The tool reports whatever the target agent replied.

Action Tools

Embed a single action in a tool. The action is not part of the graph — the tool builds and runs it when the model calls, and the tool result is whatever the action returned.

Each field of the action is either fixed by you (raw) or filled by the model (param).

toolConfigs:
  - type: action
    name: post_comment
    description: "Post a comment on the pull request"
    params:
      - body
    actionConfig:
      type: github_post
      config:
        integration:
          type: raw
          value: gh-app-main
        repo:
          type: raw
          value: "{{ .github.repo }}"
        pr_number:
          type: raw
          value: "{{ .github.pr_number }}"
        body:
          type: param
          value: body

Action Config Fields

Field	Description
type	An action type, for example http or github_post. Must be a registered action
config	The action’s fields, each as {type, value}

Field kind	type	value means
Author-fixed	raw	The value itself — a template, resolved per call. A boolean field must hold a real true/false, not the string
Model-filled	param	The name of the tool parameter the model fills in

---

Common Patterns

RAG (Retrieval-Augmented Generation)

Combine vector search with an agent for knowledge-based responses:

actions:
  search_knowledge:
    type: fetchvectors
    config:
      integration: my_qdrant
      vector: "{{ .query_embedding }}"
      options:
        collection: knowledge_base
        limit: 5
    next: action.answer_with_context

  answer_with_context:
    type: agent
    config:
      providerID: 2
      systemPrompt: |
        Answer the user's question using only the provided context.
        If the context doesn't contain relevant information, say so.

        Context:
        {{ range .search_knowledge }}
        - {{ .content }}
        {{ end }}
      userPrompt: "{{ param \"question\" }}"

Multi-Tool Agent

An agent with several workflow tools:

actions:
  smart_assistant:
    type: agent
    config:
      providerID: 2
      systemPrompt: |
        You are an assistant that can help with user management.
        Use the provided tools to look up or list users.
      userPrompt: "{{ param \"request\" }}"
      toolConfigs:
        - type: workflow
          name: get_user
          description: "Get user details by ID"
          params:
            - user_id
          workflowConfig:
            id: lookup-user
        - type: workflow
          name: list_users
          description: "List all users, optionally filtered by status"
          params:
            - status
          workflowConfig:
            id: list-users

Content Generation

Generate content with specific formatting:

actions:
  generate_email:
    type: agent
    config:
      providerID: 2
      systemPrompt: |
        You are a professional email writer. Generate emails that are:
        - Clear and concise
        - Professional in tone
        - Properly formatted with greeting and signature
      userPrompt: |
        Write an email about: {{ param "topic" }}
        Recipient: {{ param "recipient_name" }}
        Tone: {{ param "tone" }}
    next: action.send_email

---

Next Steps

Vector Operations

Build RAG pipelines with vector search.

Data Operations

Connect agents to your database.

HTTP Requests

Call external APIs from your workflows.

Actions Overview

Learn the fundamentals of ServFlow actions.