Documentation

Everything you need to know to build, configure, and deploy AI agents with AiFlow.

Quick Start

Sign in

Click Sign In to authenticate with your Google account. This creates your AiFlow account automatically.

Add provider credentials

Go to Settings in the dashboard and add API keys for the LLM providers you want to use (OpenAI, Anthropic, Google, etc.).

Create an agent

Navigate to Agents → Create Agent. Give it a name, write system instructions, and add at least one provider model.

Start chatting

Open the agent's test page or use the REST API to send messages. Sessions are created automatically on first message.

Quick API example

curl -X POST https://service.flow.nineforge.com/api/v1/chat \
  -H "Authorization: Bearer ak_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "your-agent-id",
    "messages": [{
      "role": "user",
      "content": [{ "type": "text", "text": "Hello!" }]
    }],
    "stream": true
  }'

Core Concepts

Agents

An agent is the core unit of AiFlow. Each agent has a name, system instructions (prompt), a response format, and configuration for tools, providers, and behavior. Agents are stateless between sessions but can maintain persistent memory through the soul canvas and user profiles.

System Instructions

The core prompt that defines the agent's personality, expertise, and behavioral rules.

Response Format

Choose between free-form text or structured JSON schema output for programmatic use cases.

Sessions

A session is a conversation thread between a user and an agent. Each session maintains its own message history and can accumulate turn events (tool calls, reasoning, tasks). Sessions are automatically created when you send the first message and persist until explicitly deleted.

Turn Events

Every interaction produces turn events that capture the full lifecycle: reasoning traces, tool call starts and results, provider tool outputs, task progress, and the final assistant text. These events are stored alongside messages for rich replay and debugging.

FrontAgent

FrontAgent is the conversational layer that sits between users and the engine. It manages session resolution, message routing, reactive inference (agent-initiated responses), and SSE streaming. Each account has a FrontAgent Durable Object that orchestrates all interactions.

Providers

AiFlow supports 13+ LLM providers. Each agent can have multiple providers configured in a priority chain. If the first provider fails or is unavailable, the engine automatically falls back to the next one.

openai

OpenAI

anthropic

Anthropic

google

Google (Gemini)

bedrock

AWS Bedrock

azure

Azure OpenAI

deepseek

DeepSeek

groq

Groq

mistral

Mistral

fireworks

Fireworks

xai

xAI (Grok)

cohere

Cohere

together

Together AI

openrouter

OpenRouter

Provider configuration

Each provider on an agent can be configured with model-specific settings:

temperature — Sampling temperature (0-2)

maxTokens — Maximum output tokens

topP — Nucleus sampling threshold

reasoningEffort — Low / medium / high (OpenAI)

Channels

AiFlow exposes several external chat channels. Some are fully self-serve, while others are production-ready managed deployments that are operated by Nineforge and enabled once their credentials, entry links, and platform setup are provisioned.

Slack

Production Ready

OAuth install, verified webhooks, inbound messages, and outbound replies are implemented.

Recommended channel integration.

Phase 1

OAuth

Production Ready

Webhook verification, deep-link onboarding, inbound messages, and outbound rich replies are implemented.

Recommended channel integration.

Phase 1

Link Code

Google Chat

Production Ready (Managed)

Verified inbound auth, managed onboarding, threaded replies, and native Google Chat cards are implemented for the centrally managed AiFlow app.

Operator-managed rollout: publish the managed app, configure the service account and webhook auth, then provide the public entry link.

Phase 2

Link Code

Microsoft Teams

Production Ready (Managed)

Verified Bot Framework activities, managed onboarding, and Adaptive Card replies are implemented for the centrally managed AiFlow Teams app.

Operator-managed rollout: publish the Teams app package, configure bot credentials, and expose the managed entry link.

Phase 2

Link Code

Production Ready (Managed)

Verified webhook auth, batched inbound handling, and native WhatsApp replies are implemented for the centrally managed AiFlow number.

Operator-managed rollout: configure the business number, webhook verify token, app secret, access token, and public entry link.

Phase 3

Link Code

Messenger

Production Ready (Managed)

Verified webhook auth, batched inbound handling, and native Messenger template replies are implemented for the centrally managed AiFlow page.

Operator-managed rollout: complete page/app review, configure webhook secrets and page token, and publish the managed entry link.

Phase 3

Link Code

Discord

Production Ready (Managed)

Verified interactions, DM-only relay ingress, outbound sends, and authenticated gateway-relay handling are implemented for the managed Discord bot.

Operator-managed rollout: deploy the managed bot and relay, configure the application ID plus signing or relay secrets, and publish the entry link.

Phase 2

Link Code

Managed Channel Rollout Checklist

Managed channels are production-ready only after the platform-side rollout work is completed alongside the code deployment.

Google Chat / Teams
Publish the managed app, configure service credentials, verify webhook auth, and confirm the managed install link works end to end.

WhatsApp / Messenger
Complete business or page review, configure verify tokens and app secrets, confirm webhook subscriptions, and validate the public entry link.

Discord
Deploy the managed bot and relay, configure the application ID plus signing or relay secrets, and verify DM onboarding plus outbound delivery.

All managed channels
Document webhook URLs, secret rotation, staging smoke tests, and operator runbooks before go-live.

Tools

Agents can use five types of tools. Each tool type has its own configuration and execution model.

MCP Server Tools

Connect any MCP-compatible server over HTTP+SSE. AiFlow discovers available tools from the server and exposes them to the agent. Supports authentication via bearer tokens, custom headers, query params, or basic auth using stored secrets.

{
  "type": "mcp",
  "name": "GitHub MCP",
  "transport": "http_sse",
  "url": "https://mcp.github.com/sse",
  "auth": {
    "secretId": "sec_...",
    "method": "bearer"
  }
}

HTTP API Tools

Define custom HTTP endpoints as tools with configurable methods, headers, body templates, and response mappings. The agent calls these like any other tool, and AiFlow handles the HTTP request lifecycle.

{
  "type": "http",
  "name": "get_weather",
  "url": "https://api.weather.com/v1/current",
  "method": "GET",
  "parameters": [
    { "name": "city", "type": "string", "required": true }
  ]
}

Code Tools

Write tools in TypeScript, JavaScript, or Python. The code runs in a sandboxed environment with configurable execution time, memory limits, and network access. Code tools can install packages and interact with the file system.

{
  "type": "code",
  "name": "calculate",
  "language": "typescript",
  "code": "export default function({ expression }) {\n  return String(eval(expression));\n}",
  "parameters": [
    { "name": "expression", "type": "string", "required": true }
  ]
}

Protocols

Every agent in AiFlow is automatically exposed via three interoperability protocols, but they are not all at the same maturity level for external consumers.

MCP

Strongest Support

Model Context Protocol

Agents expose their tools as MCP-compatible endpoints. The current server is shared across agents, so callers must include agentId in JSON-RPC params when listing tools or calling them.

GET /.well-known/mcp/<agent-id>

A2A

Beta

Agent-to-Agent

Google's A2A protocol for direct agent communication. AiFlow supports the inbound server flow, task submission, status lookup, cancel, and streaming. Remote outbound A2A client support is still more limited than MCP.

GET /.well-known/a2a/<agent-id>

UCP

Experimental

Universal Context Protocol

Contextual data exchange supporting text, files, URLs, images, code, and structured data. The current implementation is useful for AiFlow-aware clients, but should still be treated as an experimental external interface.

GET /.well-known/ucp/<agent-id>

Task System

Agents can create and manage autonomous tasks that run independently. Tasks support scheduling, cron patterns, and cross-agent delegation.

Trigger Types

immediate — Runs right away in the background

scheduled — Runs at a specific future time

cron — Repeats on a cron schedule

webhook — Triggered by an external HTTP call

Task Lifecycle

pending

Task created, awaiting trigger

scheduled

Waiting for scheduled time

running

Actively executing with step tracking

completed

Finished successfully with output

Task scope & delegation

Tasks can be scoped to a session, agent, or account level. Agents can delegate tasks to other agents in the same account, enabling multi-agent workflows. Task updates trigger wake notifications so the originating agent can react to results.

Skills

Skills are reusable code functions stored on the agent. Unlike one-off code execution, skills persist across sessions and can be invoked by name, building a growing library of capabilities.

Skill management

Agents with the skills builtin enabled can create, edit, list, and delete skills. Skills support TypeScript, JavaScript, and Python with typed parameters.

Skill invocation

In invoke_only mode, agents can call existing skills but not modify them. In full_management mode, agents have full CRUD access.

Example skill definition

// skills/summarize.ts
// @param url string - The URL to fetch and summarize
export default async function({ url }: { url: string }) {
  const res = await fetch(url);
  const text = await res.text();
  return `Content (${text.length} chars): ${text.slice(0, 500)}...`;
}

Agency & Self-Shaping

Agency features allow agents to evolve and personalize their behavior over time. These are opt-in capabilities that give agents a degree of autonomy.

Soul Canvas

A persistent, mutable text space the agent can read and write. Use it for long-term memory, personality traits, learned preferences, or evolving knowledge that persists across all sessions.

Directives

Self-imposed behavioral rules the agent creates for itself. These are injected into the system prompt and persist until the agent removes them. Useful for learned guidelines.

User Profiling

Agents build per-user knowledge profiles that are injected into context. This enables personalization: remembering preferences, communication style, past interactions, and relevant details.

API Reference

All API endpoints are available at https://service.flow.nineforge.com/api/v1. Authenticate with a Bearer token (JWT from Google SSO or an API key prefixed with ak_).

POST

/chat

Send a message and stream the response

GET

/agents

List all agents

POST

/agents

Create a new agent

GET

/agents/:id

Get agent details with providers and tools

PATCH

/agents/:id

Update agent configuration

GET

/sessions

List sessions (filterable by agent)

POST

/sessions

Create a new session

GET

/sessions/:id/messages

Get session message history

GET

/sessions/:id/events

Get session turn events

GET

/tasks

List tasks (filterable by status)

GET

/tasks/:id

Get task details with steps and events

POST

/front/message

Send message via FrontAgent (SSE stream)

GET

/front/events

Engine activity SSE stream

GET

/front/notifications

Reactive inference notifications

POST

/files/upload

Upload files to scoped storage

GET

/files/browse

Browse files and folders

GET

/models

List available models from all providers

GET

/credentials

List provider credentials

GET

/secrets

List stored secrets

Streaming chat example

const response = await fetch('/api/v1/front/message', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ak_your_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    message: 'Analyze the latest sales data',
    agentId: 'agent-id',
    sessionId: 'session-id', // optional
  }),
});

// Response is an SSE stream
const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;

  const lines = decoder.decode(value).split('\n');
  for (const line of lines) {
    if (!line.startsWith('data: ')) continue;
    const event = JSON.parse(line.slice(6));

    switch (event.type) {
      case 'content_delta':
        process.stdout.write(event.delta);
        break;
      case 'tool_call_start':
        console.log(`Tool: ${event.toolCall.name}`);
        break;
      case 'done':
        console.log('\nComplete');
        break;
    }
  }
}

Documentation

Quick Start

Sign in

Add provider credentials

Create an agent

Start chatting

Quick API example

Core Concepts

Agents

Sessions

Turn Events

FrontAgent

Providers

Provider configuration

Channels

Slack

Telegram

Google Chat

Microsoft Teams

WhatsApp

Messenger

Discord

Managed Channel Rollout Checklist

Tools

MCP Server Tools

HTTP API Tools

Code Tools

Built-in Tools

Provider-Native Tools

Protocols

Model Context Protocol

Agent-to-Agent

Universal Context Protocol

Task System

Trigger Types

Task Lifecycle

Task scope & delegation

Skills

Skill management

Skill invocation

Example skill definition

Agency & Self-Shaping

Soul Canvas

Directives

User Profiling

API Reference

Streaming chat example