Agents Guide

Agents are the core building blocks of CrewForm. Each agent is an AI worker configured with a specific model, system prompt, and capabilities.

Creating an Agent

Navigate to Agents → New Agent or use the + button.

Required Fields

Field	Description
Name	Human-readable identifier (e.g., “Code Reviewer”)
Model	LLM model to use (see Supported Models)
System Prompt	Instructions that define the agent’s behavior

Optional Fields

Field	Description
Description	What the agent does (shown in marketplace)
Temperature	Creativity level (0.0 = deterministic, 1.0 = creative)
Max Tokens	Maximum response length
Tags	Categorization for search and marketplace

Supported Models

CrewForm supports three LLM providers. You must add your API key in Settings → API Keys before using a provider.

Anthropic (Claude)

Model	Best For
`claude-sonnet-4-20250514`	General-purpose, balanced cost/quality
`claude-3-5-haiku-20241022`	Fast, cost-effective tasks
`claude-3-opus-20240229`	Complex reasoning, analysis

Google (Gemini)

Model	Best For
`gemini-2.0-flash`	Fast, multimodal tasks
`gemini-1.5-pro`	Long-context, complex tasks

OpenAI (GPT)

Model	Best For
`gpt-4o`	General-purpose, fast
`gpt-4-turbo`	Complex reasoning
`gpt-3.5-turbo`	Simple, high-volume tasks

Writing System Prompts

The system prompt defines your agent’s personality, expertise, and output format. Tips:

Be Specific

❌ "You are a helpful assistant."
✅ "You are a senior code reviewer specializing in TypeScript and React.
    You review code for bugs, performance issues, and best practices.
    Output your review as a numbered list with severity (HIGH/MEDIUM/LOW)."

Define Output Format

You must respond in the following JSON format:
{
  "summary": "one-line summary",
  "findings": [{ "severity": "HIGH|MEDIUM|LOW", "description": "..." }],
  "recommendation": "overall recommendation"
}

Set Boundaries

You ONLY review code. If asked to write new code, respond with:
"I'm configured as a reviewer. Please create a separate coding agent."

Agent Lifecycle

Created → Idle → Running (task assigned) → Idle
                    ↓
               Failed (error)

Idle: Ready to accept tasks
Running: Actively processing a task
Failed: Task errored — check the task detail for the error message

Output Routes

By default, when an agent completes a task, the result is broadcast to all active output routes (HTTP webhooks, Slack, Discord, Telegram, Teams, Asana, Trello) in your workspace. See the Output Routes guide for how to configure destinations. You can restrict an agent to deliver results to specific channels only:

Open the agent in Agents → [Agent Name] → Settings
Scroll to Output Routes
Select one or more channels from the dropdown — or leave blank to send to all

Leave blank (default) = broadcast to all active routes. Select specific channels to narrow delivery.

This is useful when you have multiple output routes (e.g., a #dev-alerts Slack channel and a Telegram group) and only want certain agents to send to specific ones.

How it works

Under the hood, the agent stores a list of route UUIDs in output_route_ids:

Value	Behaviour
`null` (default)	Dispatch to all active output routes
`[]` (empty array)	Dispatch to no routes
`[uuid, ...]`	Dispatch to only those specific routes

Voice Profiles

Voice profiles let you control how an agent communicates — its tone, style, and formatting preferences. When a voice profile is configured, it’s injected into the system prompt as a ## Voice & Tone section before each execution.

Configuring a Voice Profile

Open an agent → click the Voice Profile tab
Select a Tone Preset — Formal, Casual, Technical, Creative, Empathetic, or Custom
Add Custom Voice Instructions — e.g. “Always refer to customers as ‘members’. Use active voice. Avoid jargon.”
Add Output Format Hints (optional) — e.g. “Use numbered lists for steps. Keep responses under 200 words.”
Click Save Voice Profile

Tone Presets

Preset	Style
Formal	Professional, structured, precise
Casual	Friendly, conversational, approachable
Technical	Detailed, accurate, documentation-style
Creative	Expressive, engaging, vivid language
Empathetic	Warm, supportive, understanding
Custom	Define your own tone

Brand Voice Templates

You can save a voice profile as a reusable Brand Voice Template that other agents can share:

Configure the tone, instructions, and format hints
Click Save as Template → give it a name (e.g. “Acme Brand Voice”)
On any other agent, select the template from the Brand Voice Template dropdown

This ensures all customer-facing agents (or all internal agents) use the same voice consistently.

How It Works at Runtime

When the agent runs a task, the system prompt is constructed as:

[Agent's base system prompt]

## Voice & Tone
Tone: formal
Always refer to customers as 'members'. Use active voice. Avoid jargon.
Output format: Use numbered lists for steps. Keep responses under 200 words.

[Task instructions]

Voice profiles work across all execution modes — standalone tasks, pipeline steps, orchestrator delegations, and collaboration discussions.

Output Templates

Output templates let you format agent output consistently using {{variable}} placeholders. Instead of raw LLM text, results are wrapped in a structured template.

Configuring an Output Template

Open an agent → click the Output Template tab
Select a Template Type — Markdown, JSON, HTML, CSV, or Custom
Write the Template Body using {{variable}} syntax:

# {{task_title}}

> Generated by **{{agent_name}}** on {{timestamp}}

{{task_result}}

---
*Tokens used: {{tokens_used}} · Model: {{model}}*

Click Preview to see it rendered with sample data
Click Save Template

Available Variables

Variable	Description
`{{task_title}}`	Title of the task
`{{task_result}}`	Full output from the agent
`{{agent_name}}`	Name of the agent that ran the task
`{{timestamp}}`	ISO 8601 timestamp of completion
`{{tokens_used}}`	Total tokens used during execution
`{{model}}`	Model ID used for execution

How It Works at Runtime

After the LLM generates its response, the output template is applied:

LLM raw output → {{task_result}} slot in template → Final formatted result

Missing variables are left as {{variable_name}} in the output, so templates degrade gracefully.

MCP Server Publishing

You can expose any agent as an MCP tool that Claude Desktop, Cursor, or any MCP-compatible client can call directly.

Publishing an Agent

Open the agent in Agents → [Agent Name]
Click the MCP Publish button in the header bar
The button changes to MCP Published (green) — the agent is now exposed as an MCP tool

Click again to unpublish. The agent immediately appears/disappears from the MCP tool list.

What Happens

When published, the agent becomes callable via the MCP protocol:

Property	Value
Tool Name	Lowercase agent name, alphanumeric + underscores (e.g., “Code Reviewer” → `code_reviewer`)
Description	Agent’s description field
Input	A `message` string — the prompt or task to send
Execution	Full agent execution — same model, system prompt, tools, knowledge base, and voice profile as running from the UI

Connecting External Clients

Go to Settings → MCP Servers
Click Generate MCP API Key to create a cf_mcp_ prefixed key
Copy the auto-generated config snippet into your client:

{
  "mcpServers": {
    "crewform": {
      "url": "https://runner.crewform.tech/mcp",
      "headers": {
        "Authorization": "Bearer cf_mcp_your_key_here"
      }
    }
  }
}

Each API key is scoped to a single workspace — only that workspace’s published agents are visible. See the full MCP Server Publishing Guide for detailed setup instructions.

Export & Import

Exporting an Agent

Open the agent in Agents → [Agent Name]
Click the Export button in the header bar
A crewform-agent-{name}.json file downloads automatically

The export includes: model, system prompt, temperature, max tokens, tags, tools, voice profile, and config. It does not include workspace-specific data like API keys, task history, or custom tools.

Importing an Agent

Navigate to Agents list page
Click the Import button in the top-right
Select a .json file (CrewForm export format)
The agent is created with an (imported) suffix

Importing a team export file from the Agents page will import the team and all its member agents.

Export Format

Exports use a versioned crewform-export format (v1) for forward compatibility:

{
  "format": "crewform-export",
  "version": 1,
  "type": "agent",
  "exported_at": "2026-04-08T12:00:00.000Z",
  "data": {
    "name": "Code Reviewer",
    "model": "claude-sonnet-4-20250514",
    "system_prompt": "You are an expert code reviewer...",
    "tools": ["web_search", "knowledge_search"],
    ...
  }
}

Using Agents in Teams

Agents become more powerful when combined into teams. See the Pipeline Teams Guide for multi-agent workflows.

API Key Security

All API keys are encrypted with AES-256-GCM before storage. Keys are:

Encrypted client-side before being sent to the database
Never stored in plaintext
Only decrypted by the task runner at execution time
Scoped to your workspace via Row-Level Security

See [Settings → API Keys] in the app to manage your provider keys.

​Agents Guide

​Creating an Agent

​Required Fields

​Optional Fields

​Supported Models

​Anthropic (Claude)

​Google (Gemini)

​OpenAI (GPT)

​Writing System Prompts

​Be Specific

​Define Output Format

​Set Boundaries

​Agent Lifecycle

​Output Routes

​How it works

​Voice Profiles

​Configuring a Voice Profile

​Tone Presets

​Brand Voice Templates

​How It Works at Runtime

​Output Templates

​Configuring an Output Template

​Available Variables

​How It Works at Runtime

​MCP Server Publishing

​Publishing an Agent

​What Happens

​Connecting External Clients

​Export & Import

​Exporting an Agent

​Importing an Agent

​Export Format

​Using Agents in Teams

​API Key Security

Agents Guide

Creating an Agent

Required Fields

Optional Fields

Supported Models

Anthropic (Claude)

Google (Gemini)

OpenAI (GPT)

Writing System Prompts

Be Specific

Define Output Format

Set Boundaries

Agent Lifecycle

Output Routes

How it works

Voice Profiles

Configuring a Voice Profile

Tone Presets

Brand Voice Templates

How It Works at Runtime

Output Templates

Configuring an Output Template

Available Variables

How It Works at Runtime

MCP Server Publishing

Publishing an Agent

What Happens

Connecting External Clients

Export & Import

Exporting an Agent

Importing an Agent

Export Format

Using Agents in Teams

API Key Security