AI Agents

AI Agents let you run autonomous tasks in the cloud that are grounded in your organization's knowledge graph. Each agent runs inside an isolated sandbox with full access to the ai CLI, meaning it can search, read, create, and link knowledge nodes as part of its work.

Setup

There are two ways to run agents, depending on how you want to handle billing:

Option A: Use your personal Claude subscription (OAuth)

If you have a Claude Max subscription, agents can run on your personal subscription instead of an organization API key. This requires SSO login:

# Log in with SSO
ai login --sso

# Register your tokens (auto-detects Claude Code OAuth token)
ai agent register

On macOS, the command auto-detects your Claude Code OAuth token from the system Keychain. On Linux, it reads from ~/.claude/.credentials.json. If auto-detection fails, you can paste your token manually (run claude setup-token to get it).

The organization still needs an E2B API key configured (see Option B), but the Claude usage bills to your personal subscription.

To remove your registered tokens:

ai agent unregister

Option B: Use an organization API key

Configure organization-level API keys. You need a Claude API key (from Anthropic) and an E2B API key (from e2b.dev):

ai agent config set

This interactive command prompts for your Claude API key, E2B API key, default model, timeout, and an optional prompt template. All keys are encrypted at rest.

Verify your configuration:

ai agent config

Agent Types

Agents come in 6 specialized types, each with different tools, templates, and capabilities:

List all types with:

ai agent types

Custom Agent Types

Organizations can create custom agent types with their own prompts, or override the prompts of built-in types. Custom types use a lightweight sandbox with Node.js and the ai CLI.

# Create a custom agent type
ai agent types create \
  --slug qa-tester \
  --label "QA Tester" \
  --prompt "You are a QA testing agent. Analyze code for bugs and edge cases." \
  --timeout 20

# Read the prompt from a file instead
ai agent types create --slug analyst --label "Analyst" --prompt-file ./analyst-prompt.md

# Override a built-in type's prompt
ai agent types create \
  --slug researcher \
  --override \
  --prompt "You are a research agent for our org. Always check internal docs first."

# Update an existing type
ai agent types update qa-tester --prompt "Updated prompt text"

# Delete a custom type or override
ai agent types delete qa-tester

Custom types appear with a [custom] badge and overrides with an [overridden] badge when listing types. Use --type to run an agent with a custom type:

ai agent "Find edge cases in the auth module" --type qa-tester

MCP Servers for Agents

Organizations can register MCP servers that agents can use inside their sandboxes. This lets agents access external tools (GitHub, Slack, databases, etc.) via the Model Context Protocol. Only npx-based servers are supported.

# Register an MCP server
ai agent mcp add \
  --name github \
  --package @modelcontextprotocol/server-github \
  --env GITHUB_PERSONAL_ACCESS_TOKEN=ghp_your_token

# Scope to specific agent types
ai agent mcp add \
  --name slack \
  --package @modelcontextprotocol/server-slack \
  --env SLACK_TOKEN=xoxb-your-token \
  --types researcher,planner

# List registered servers
ai agent mcp list

# Update a server
ai agent mcp update github --env GITHUB_PERSONAL_ACCESS_TOKEN=ghp_new_token

# Remove a server
ai agent mcp remove github

Registered MCP servers are automatically injected into the agent sandbox as a .mcp.json file. Claude Code discovers them at startup and makes their tools available to the agent. Environment variables are encrypted at rest.

Agent Secrets

Some agent types require per-user secrets (GitHub PAT for developer/reviewer/planner, database connections for data agents). These are encrypted at rest, per user:

# Register a GitHub PAT (for planner, developer, reviewer agents)
ai agent secrets set --github-pat ghp_your_token

# Register database connections (for data agents)
ai agent secrets set --db crm --db-type postgres postgresql://...
ai agent secrets set --db letting --db-type mssql "Server=...;Database=..."

# Check what's configured
ai agent secrets show

# Remove all secrets
ai agent secrets delete

Running an Agent

Pass a natural language prompt describing the task. Use --type to select the agent type (defaults to researcher):

# Research (default type)
ai agent "Research the latest GDPR changes and add findings to our compliance nodes"

# Brainstorming
ai agent "How could we improve our onboarding flow?" --type brainstormer

# Planning
ai agent "Plan the implementation of user notifications" --type planner

# Development
ai agent "Implement issue #42 in org/repo" --type developer

# Code review
ai agent "Review PR #15 in org/repo" --type reviewer

# Data analysis
ai agent "What's the monthly active user trend in the CRM database?" --type data

The CLI submits the task, then polls for the result. The agent runs in the cloud and typically completes in 1-5 minutes depending on complexity.

Options

# Use a specific workspace for context
ai agent "Summarize recent decisions" -w engineering

# Use Opus for complex reasoning tasks
ai agent "Cross-reference our architecture docs with the codebase" -m opus

# Fire and forget
ai agent "Update stale research nodes" --no-wait

Prompt Templates

Organizations can set a custom prompt template that applies to all agent runs. This is useful for establishing guardrails, output formats, or domain-specific instructions.

Set a template during configuration:

ai agent config set
# When prompted for "Prompt template", enter your instructions

Example templates:

# Research-focused org
"Always cite sources. Create nodes as draft status.
Use type 'research' for findings and 'analysis' for interpretations.
Link findings to existing relevant nodes."

# Compliance-focused org
"Never delete existing nodes. Always create as draft for human review.
Tag compliance-related findings with domain 'legal'.
Include regulatory references in node metadata."

Managing Runs

List recent runs

ai agent runs
ai agent runs --limit 20 --status completed

Check a specific run

ai agent status <run-id>

Run statuses: pending (queued), running (executing), completed (success), failed (error), timeout (exceeded max timeout).

How It Works

When you run ai agent "prompt":

1. The API validates your configuration and creates a run record.
2. An isolated cloud sandbox (E2B Firecracker microVM) spins up in ~100ms.
3. Authentication is injected based on your auth mode:
   • OAuth: Your Claude subscription token and Apart Intelligence credentials are written into the sandbox.
   • API key: The org's Claude API key and Apart Intelligence API key are set as environment variables.
4. If the org has registered MCP servers, a .mcp.json config is written into the sandbox.
5. A prompt is assembled from: your org's template + agent type prompt + CLI reference + your task.
6. Claude Code executes inside the sandbox, using ai commands and any MCP tools to interact with the graph and external services.
7. Results are captured and the sandbox is destroyed.

Scheduled Agents

Agents can run on a recurring schedule using cron expressions. Create a schedule and the system uses Google Cloud Scheduler to trigger agent runs automatically.

# Create a schedule
ai agent schedule create --name "Daily report" --cron "0 8 * * MON-FRI" \
  --prompt "Summarize the knowledge graph health" --type researcher

# List schedules
ai agent schedule list

# Pause / resume / delete
ai agent schedule pause <id>
ai agent schedule resume <id>
ai agent schedule delete <id>

See the Scheduled Agents guide for full details on cron expressions, API endpoints, and how scheduling works.

Configuration Reference