Skip to main content

Creating A2A Agents

A2A agents are MCPBundles assistants that run on a schedule, respond to webhooks, or accept programmatic SendMessage calls from other software — all through the Agent-to-Agent protocol. They follow markdown instructions, call your MCP tools, and keep a run history.

Example use cases:

  • Daily email review — Check your inbox every morning and summarize important messages
  • Content monitoring — Review social posts and flag items needing attention
  • Data analysis — Run weekly reports and identify trends
  • Task automation — Check project status and create follow-up tasks

What Are A2A Agents?​

An A2A agent is an AI assistant that:

  • Runs automatically on a schedule you set (every hour, daily, weekly, etc.)
  • Can also be triggered by webhooks or Hub / API callers
  • Follows instructions you provide in markdown files
  • Uses tools from MCP servers you've enabled
  • Publishes an Agent Card at a unique slug for A2A clients
  • Keeps a history of what it's done

Think of it like: Setting up a recurring task, but instead of you doing it, an A2A agent does it for you — and other programs can invoke the same agent through A2A when needed.

Prerequisites​

Before creating an A2A agent, you need:

Platform AI Included

A2A agents use platform AI (Anthropic) by default, so you don't need to provide your own API key. Token usage counts toward your plan limits. You can optionally add your own API key in Settings → AI keys if you prefer.

Step 1: Create Your A2A Agent​

  1. Go to Dashboard → A2A Agents
  2. Click "Create A2A Agent"
  3. Enter a Display Name (e.g., "Daily Email Reviewer")
  4. Optionally add a Description
  5. Click "Create"

Your A2A agent is created but won't run yet — you need to configure it first.

Step 2: Configure AI Settings​

A2A agents use platform AI (Anthropic) with the default model automatically. No configuration needed!

Platform AI by Default

A2A agents use platform AI (Anthropic) with the default model automatically. Token usage counts toward your plan limits. If you reach your token limit, agents will be automatically disabled until you upgrade or add your own API key.

Using Your Own API Key

You can optionally add your own Anthropic API key in Settings → AI keys. A2A agents will use your key instead of the platform key, and usage won't count toward plan limits. See Using API Keys.

Step 3: Choose MCP access (Hub or one server)​

In the Configuration tab, pick how the agent reaches tools:

OptionWhen to use
Hub (useHub)One agent that can call tools from all MCP servers connected in your workspace — good for cross-service workflows
Single MCP serverFocused agents that should only use one integration (e.g. a monitor that only touches Google Ads)
  1. Open Configuration
  2. Choose Hub or select one MCP server from the list
  3. Save the configuration
MCP access must be operational

If you pick a specific MCP server, it must be connected and have required credentials verified. If that server becomes unavailable, the agent is automatically paused. Hub-backed agents need at least one connected server with working access.

Step 4: Write Agent Instructions​

Agent instructions tell your A2A agent who it is and what it should do.

  1. Go to the "Agent Instructions" tab
  2. Write markdown content explaining:
    • Who the agent is — Its role and purpose
    • What it should do — Its goals and objectives
    • How it should behave — Guidelines and constraints

Example:

# Email Review Assistant

You are an email review assistant that helps prioritize important messages.

## Your Role
- Review emails from the past 24 hours
- Identify urgent messages that need immediate attention
- Summarize important conversations
- Flag messages requiring follow-up

## Guidelines
- Be concise in summaries
- Only flag truly urgent items
- Maintain privacy - don't share email content verbatim
  1. Click "Save"

Step 5: Create Heartbeat Checklist (optional)​

The heartbeat checklist is what your A2A agent follows on scheduled runs. It is optional if you only need manual or on-demand runs—agent instructions alone are enough for those.

For bundle MCP and CLI workflows, see Agents on MCP Servers.

When you want scheduled runs with a fixed step list:

  1. Go to the "Heartbeat Checklist" tab
  2. Write a markdown checklist of tasks:

Example:

# Daily Email Review

1. Check inbox for new emails from the past 24 hours
2. Identify emails marked as important or from key contacts
3. Summarize the 5 most important emails
4. Check for any emails requiring immediate response
5. Create a summary report
  1. Click "Save"

Your A2A agent will follow this checklist on each scheduled run (when a checklist is present).

Step 6: Set Schedule​

Configure how often your A2A agent runs:

  1. In the "Configuration" tab, find "Heartbeat Interval"

  2. Set the interval in minutes:

    • 60 minutes — Runs every hour
    • 1440 minutes — Runs once per day
    • 10080 minutes — Runs once per week
    • Or any custom interval (minimum 5 minutes)

  3. Click "Save Configuration"

Step 7: Activate Your A2A Agent​

Before scheduled runs can start, save Agent Instructions and set a Heartbeat Interval in Configuration. A Heartbeat Checklist is optional but helps scheduled runs follow a fixed step list.

Click Activate schedule to turn on the interval you configured. Manual runs and webhooks work without activating the schedule.

Once the schedule is active, your A2A agent runs automatically at the interval you set.

Token Limits

If your workspace reaches its AI token limit, A2A agents will be automatically disabled. Upgrade your plan or add your own API key to continue running agents.

Monitoring Your A2A Agent​

View Execution History​

  1. Go to your agent's page
  2. Click the "History" tab
  3. See all past runs with:
    • Status — Success, Failed, or Running
    • Started At — When the run began
    • Duration — How long it took
    • Tool Calls — How many tools were used

View Run Details​

Click on any run to see:

  • What tools were called
  • The agent's response
  • Any errors that occurred
  • Token usage

Check Agent Status​

On your agent's page, you'll see:

  • Status Badge — Active (green), Inactive (gray), Suspended (red), or Blocked
  • Last Heartbeat — When it last ran
  • Next Run — When it will run next (estimated)

Agent Status Explained​

  • Active — A2A agent is running on schedule
  • Inactive — Agent is paused and won't run
  • Suspended — Agent has an issue (missing configuration, MCP server unavailable, etc.) and is automatically paused
  • Blocked — Agent is blocked due to a critical error

Adding Skills (Optional)​

Skills are additional capabilities you can give your A2A agent beyond the basic instructions.

  1. Go to the "Skills" tab
  2. Click "Add Skill"
  3. Enter:
    • Skill Name — What the skill is called
    • Content — Markdown explaining the skill
  4. Click "Add Skill"

Example Skill:

# Data Analysis

When analyzing data:
- Look for trends over time
- Identify outliers
- Compare current period to previous period
- Highlight significant changes (>10%)

Skills are available to your A2A agent but aren't required — they're helpful for complex workflows.

Manual Execution​

You can trigger your A2A agent to run immediately without waiting for the schedule:

  1. On your agent's page, click "Run"
  2. Your agent will execute its instructions right away (and its heartbeat checklist when one is configured)
  3. View the results in the History tab

Note: Manual runs still count toward your schedule — you won't get duplicate runs for the same time slot.

Stopping or canceling a run​

If an A2A agent run is still Running, you can stop it from the dashboard:

  1. Open the agent's History tab (or the run detail page from a notification).
  2. Click Stop Run on the in-progress run.
  3. The run status changes to Cancelled — the agent stops calling tools for that run.

Programmatic callers can cancel an in-flight A2A task through the Hub cancel_agent_task tool using the task_id returned from trigger_agent_run. The same cancel_agent_task and get_agent_task tools are available on bundle MCP connections for agents bound to that server.

Stopping a run does not deactivate the agent — scheduled and manual runs can still start afterward.

Editing Your A2A Agent​

You can update your agent at any time:

  • Edit Instructions — Update the "Agent Instructions" tab
  • Edit Checklist — Update the "Heartbeat Checklist" tab
  • Change Schedule — Update the heartbeat interval
  • Switch MCP servers — Change which MCP server the agent uses

Changes take effect on the next run.

Deactivating or Deleting​

Deactivate (Pause)​

Click "Deactivate" to pause your A2A agent. It will stop running but keep all its configuration and history.

Delete​

Click "Delete" to permanently remove your A2A agent and all its history. This cannot be undone.

Best Practices​

Writing Good Instructions​

  • Be specific — Clear goals work better than vague instructions
  • Set boundaries — Tell your agent what NOT to do
  • Provide context — Explain why tasks matter
  • Use examples — Show what good output looks like

Writing Effective Checklists​

  • Number your tasks — Makes it clear what order to follow
  • Be actionable — Each item should be something the agent can do
  • Use tools — Reference specific tools your agent can call
  • Keep it focused — Don't try to do too much in one run

Managing Costs​

  • Monitor token usage — Check run history to see how many tokens each run uses
  • Track plan limits — Token usage counts toward your plan's monthly limit
  • Set per-run limits — Configure max tokens per run if needed
  • Optimize frequency — Don't run more often than necessary
  • Review failures — Failed runs still use tokens, so fix issues quickly
  • Use your own API key — Add your own Anthropic API key to bypass plan limits

Troubleshooting​

Agent Won't Activate​

Check:

  • Agent Instructions are saved (not empty)
  • For scheduled runs: Heartbeat Interval is set and you clicked Activate schedule (checklist optional)
  • Workspace hasn't reached token limit (A2A agents are auto-disabled at limit)

Agent Shows "Suspended" or "Inactive"​

Common causes:

  • MCP server is disabled or unavailable
  • MCP server credentials are invalid
  • Missing agent instructions
  • Schedule not activated (Activate schedule) or heartbeat interval missing
  • Workspace reached AI token limit (agent auto-disabled)

Fix:

  • Check MCP server status and credentials
  • Ensure all required fields are filled
  • Check if workspace is at token limit (upgrade plan or add your own API key)
  • Reactivate the agent

Agent Runs But Does Nothing​

Check:

  • Heartbeat checklist has actionable tasks
  • Checklist references tools that exist
  • Tools are available from the selected MCP server
  • Review run history to see what happened

High Token Usage or Agent Auto-Disabled​

If agent was auto-disabled:

  • Your workspace reached its monthly AI token limit
  • Upgrade your plan to increase limits
  • Or add your own Anthropic API key in Settings → AI keys (usage won't count toward plan limits)

To reduce token usage:

  • Simplify your instructions and checklist
  • Reduce the frequency of runs
  • Set a max tokens limit per run
  • Review run history to identify expensive operations

Next Steps​

Now that you've created your first A2A agent:

  • Monitor its runs in the History tab
  • Refine your instructions based on results
  • Add skills for more complex workflows
  • Create additional A2A agents for different tasks

Need help? Check the FAQ or contact support.