Build an agent app

Create a conversational AI agent with skills, knowledge, and triggers. Covers the full configuration flow.

Agent apps are Helix's chatbot and automation builder. An agent app has a system prompt, an LLM, optional skills (web search, APIs, MCP), optional knowledge bases (RAG), and optional triggers (Slack, cron, webhook). Users interact with it through the Helix chat UI, an embedded widget, or an API call. This guide walks the full configuration flow.

Agent apps are distinct from spec tasks and coding agents, which do autonomous software development inside sandbox containers.

Create an agent app

1. Navigate to Agents in the left sidebar.
2. Click New Agent.
3. Give the agent a name and, optionally, a description and avatar.

Helix creates a minimal agent: a default model, no system prompt, no skills.

Configure the model

Open the Settings tab. Under Model:

• Provider — choose from your configured providers (Anthropic, OpenAI, Google, Ollama, etc.). See Configure LLM providers.
• Model — pick the specific model. Available models depend on which providers are enabled.
• System prompt — the instruction context the model receives before every conversation. Write it in first person: "You are a support assistant for Acme Corp…"
• Temperature — 0 for precise and deterministic, 1 for balanced, 2 for creative.
• Max tokens — cap on the response length.
• Context limit — number of past messages included per turn (1 = no memory of prior turns; higher values increase context but cost more).

Reasoning model

For tasks that benefit from an extended thinking step before responding, enable a Reasoning model (e.g., Claude 3.7 Sonnet with extended thinking, o3). Helix will use the reasoning model for planning and the main model for the final reply.

Add skills

Skills are tools the agent can call. Enable them in the Skills tab.

Built-in skills

Toggle each skill on or off. Each skill exposes one or more tools the LLM can invoke when the user's message makes it relevant.

API integrations

Connect any REST API by providing an OpenAPI schema. The agent reads the schema and can call any endpoint when relevant.

1. Click Add API.
2. Provide a name, description, and OpenAPI schema (paste YAML/JSON or link to a URL).
3. If the API requires authentication, set the Authorization header using a secret reference: ${MY_API_KEY}.

For OAuth-protected APIs, set the OAuth provider field. The user is prompted to authorise once; the agent uses the token automatically after that.

MCP servers

Model Context Protocol lets agents connect to external tool servers. Add an MCP server in the Skills tab → Add MCP.

HTTP transport (most common for remote servers):

Name: GitHub
URL: https://mcp.example.com/github
Header: Authorization: Bearer ${GITHUB_TOKEN}

Stdio transport (runs as a subprocess inside the agent's container):

Name: Filesystem
Command: npx
Args: -y @modelcontextprotocol/server-filesystem /workspace

For OAuth-authenticated MCP servers, set the OAuth provider field.

Add knowledge bases (RAG)

Knowledge bases give the agent long-term memory over a set of documents. When the user sends a message, Helix searches the knowledge base and injects the relevant chunks into the context.

See Add RAG knowledge bases for the full knowledge source configuration.

Set up triggers

By default, the agent is only reachable through the Helix chat UI. Triggers extend that reach.

See Configure triggers for detailed setup instructions for each trigger type.

Supported triggers:

• Slack — the agent responds to @-mentions or messages in configured channels
• Microsoft Teams — same pattern as Slack
• Discord — responds to messages in configured servers/channels
• Cron — runs on a schedule with a fixed input prompt (useful for reports, summaries)
• Azure DevOps — responds to work item events
• Crisp — handles live chat conversations
• Webhook — any external system can POST to a generated URL to trigger the agent

Configure appearance

The Appearance tab controls how the agent looks when embedded:

• Name and Avatar — displayed in the chat header
• Conversation starters — suggested prompts shown to new users
• Theme — light or dark
• Allowed domains — restrict widget embedding to specific hostnames

Manage access

The Access tab controls who can use the agent:

• Private — only you
• Organisation — any member of your org
• Public — anyone with the link (no login required)

You can also share the agent with specific users.

API and embedding

The Developers tab shows:

• API endpoint and an example curl request — POST a message and receive the response (streaming or non-streaming)
• Embed snippet — drop a <script> tag into any page to add a floating chat widget
• OpenAI-compatible endpoint — use the agent as a drop-in replacement in any OpenAI SDK client

API calls authenticate with a user API key (from Account → API Keys) or an org API key (from Organisation → API Keys).

Test and evaluate

The Tests tab lets you define expected input/output pairs. Run them against the agent to catch regressions when you change the system prompt or model.

The Evaluation tab runs a broader question set and scores the agent's responses. This is useful for systematically comparing two model or prompt configurations.

Monitor usage

The Usage tab shows request counts, token consumption, and error rates over time, broken down by model and skill.