Creating Agents

This document covers how to define agent tasks, configure their behavior, and use advanced execution modes.

Task Structure

An agent task is a Firestore document in the agent_tasks collection. Each document contains the following fields:

Field	Type	Required	Description
task_id	string	auto	Generated document ID
user_id	string	auto	Owning user's UID
name	string	yes	Human-readable task name
description	string	no	Optional description of what the agent does
system_prompt	string	yes	System-level instructions for the LLM
task_prompt	string	yes	The main prompt executed each run
model	string	yes	Model ID (e.g., claude-sonnet, gpt-5.2)
tools	array	yes	Enabled tools: api_call, http_get, http_post, webhook
integrations	array	yes	Integration IDs the agent can access
webhook_urls	array	no	Pre-registered webhook URLs (max 3, HTTPS only)
schedule	string	yes	Cron expression (UTC)
max_iterations	integer	no	Override max iterations (capped by plan limit)
max_credits	integer	no	Override max credits per execution (capped by plan limit)
temperature	float	no	LLM temperature (default: 0.3)
max_tokens	integer	no	Max output tokens per LLM call (default: 4096)
enabled	boolean	auto	Whether the task is active (default: true)
created_at	timestamp	auto	Creation timestamp
updated_at	timestamp	auto	Last update timestamp

Prompts

System Prompt

The system_prompt defines the agent's persona and standing instructions. It is prepended to every LLM call within the agentic loop. Keep it concise and focused on role definition, output format requirements, and behavioral constraints.

You are a cryptocurrency market analyst. Your job is to gather current
market data, identify notable price movements, and produce a concise
daily briefing. Always cite data sources. Format output as markdown.

Task Prompt

The task_prompt is the instruction executed on each scheduled run. It supports variable substitution:

Variable	Replaced With
{{date}}	Current date (YYYY-MM-DD)
{{datetime}}	Current datetime (ISO 8601)
{{execution_id}}	Unique execution identifier
{{task_name}}	The task's name field

Generate the daily crypto market briefing for {{date}}.

1. Fetch BTC, ETH, and SOL prices from CoinGecko.
2. Check LunarCrush for social sentiment on the top 3 trending coins.
3. Summarize notable movements (>5% in 24h).
4. Post the briefing to the #market-updates Slack channel.

Schedule

Schedules use standard cron syntax (5 fields, UTC):

# Every day at 8:00 AM UTC
0 8 * * *

# Every 6 hours
0 */6 * * *

# Weekdays at 9:00 AM and 5:00 PM UTC
0 9,17 * * 1-5

# First day of each month at midnight
0 0 1 * *

Minimum interval is 5 minutes for Pro plans and 15 minutes for Guru plans.

Example: Crypto Market Briefing Agent

{
  "name": "Daily Crypto Briefing",
  "description": "Generates a daily market summary and posts to Slack",
  "system_prompt": "You are a cryptocurrency market analyst. Gather current market data, identify notable price movements, and produce a concise daily briefing in markdown format. Always cite your data sources.",
  "task_prompt": "Generate the daily crypto market briefing for {{date}}.\n\n1. Fetch BTC, ETH, and SOL prices from CoinGecko.\n2. Check LunarCrush Galaxy Score for the top 3 trending coins.\n3. Summarize any coins with >5% movement in the past 24 hours.\n4. Post the complete briefing to the #market-updates Slack channel via webhook.",
  "model": "claude-sonnet",
  "tools": ["api_call", "http_get", "webhook"],
  "integrations": ["coingecko", "lunarcrush", "slack"],
  "webhook_urls": [
    "https://example.com/webhooks/slack/market-updates"
  ],
  "schedule": "0 8 * * *",
  "max_iterations": 8,
  "max_credits": 80,
  "temperature": 0.2,
  "max_tokens": 4096
}

Tools Configuration

The tools array determines which built-in tools the agent can invoke. Only include the tools the agent actually needs. Reducing tool scope limits the agent's attack surface.

{
  "tools": ["api_call", "http_get"]
}

If the agent needs to send data to a webhook, include webhook in the tools array and register the target URLs in webhook_urls. If it needs to make authenticated API calls, include api_call and store the required credentials in the task's credential subcollection.

Integrations Configuration

The integrations array lists the platform integration IDs the agent is permitted to access. Outbound HTTP requests are blocked unless the target domain matches one of the listed integrations.

{
  "integrations": ["coingecko", "slack", "lunarcrush"]
}

See Integrations for the full list of available integration IDs and their associated domains.

Ensemble Mode

Ensemble mode runs the same prompt through multiple models and aggregates their outputs. This is useful for tasks where cross-model consensus improves accuracy, such as data analysis or classification.

To enable ensemble mode, set ensemble_enabled to true and provide the additional configuration:

{
  "ensemble_enabled": true,
  "ensemble_models": [
    "claude-sonnet",
    "gpt-5.2",
    "gemini-3.1-pro"
  ],
  "ensemble_config": {
    "strategy": "consensus",
    "min_agreement": 2,
    "aggregator_model": "claude-sonnet",
    "aggregator_prompt": "You are given outputs from multiple AI models for the same task. Synthesize them into a single, accurate response. Where models disagree, note the discrepancy."
  }
}

Ensemble Field	Description
ensemble_models	Array of model IDs to run in parallel
ensemble_config.strategy	consensus (majority vote), best_of (pick best), or synthesize (merge all)
ensemble_config.min_agreement	Minimum models that must agree (for consensus strategy)
ensemble_config.aggregator_model	Model used to aggregate/synthesize results
ensemble_config.aggregator_prompt	Prompt for the aggregator step

Each model in the ensemble consumes credits independently. The aggregator step is an additional credit charge. Total cost scales linearly with the number of ensemble models.

Swarm Mode

Swarm mode orchestrates multiple agents as a directed acyclic graph (DAG), where each agent can depend on the output of others. This enables multi-step pipelines where specialized agents handle different stages.

Swarm executions are triggered via the /internal/agent/swarm endpoint:

{
  "swarm_name": "Weekly Market Report Pipeline",
  "agents": [
    {
      "agent_id": "data_collector",
      "task_id": "task_abc",
      "depends_on": []
    },
    {
      "agent_id": "sentiment_analyzer",
      "task_id": "task_def",
      "depends_on": ["data_collector"]
    },
    {
      "agent_id": "report_writer",
      "task_id": "task_ghi",
      "depends_on": ["data_collector", "sentiment_analyzer"]
    },
    {
      "agent_id": "publisher",
      "task_id": "task_jkl",
      "depends_on": ["report_writer"]
    }
  ]
}

Each agent in the swarm is a standard task. The depends_on field lists the agent_id values whose output must be available before the agent starts. Outputs from upstream agents are injected into the downstream agent's prompt context automatically.

Agents with no dependencies run in parallel. The swarm executor manages sequencing, passes intermediate results, and tracks the overall swarm execution as a single record.

Swarm limits are calculated as the sum of individual agent limits, capped at the plan maximum. For example, a Pro plan swarm of 4 agents has a combined ceiling of 100 iterations and 2,000 credits.

Task Lifecycle

State	Description
enabled: true	Task runs on schedule
enabled: false	Task is paused; no executions are triggered
Deleted	Task document removed; pending Cloud Tasks messages are ignored on arrival

To pause a task, set enabled to false. To resume, set it back to true. Deleting a task also deletes its credentials subcollection and execution history.