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 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. A2A agents will use your key instead of the platform key, and usage won't count toward plan limits.

Step 3: Choose Tools (Hub or MCP Server)​

Your A2A agent needs access to tools to perform actions. Choose one:

Option A: Use MCP Hub (All Your Tools)​

The MCP Hub gives your agent access to all tools from every MCP server you've enabled.

  1. In the "MCP Source" section, select "Use MCP Hub"
  2. Your agent can now use any tool from any enabled MCP server

Best for: A2A agents that need tools from multiple MCP servers

Option B: Use a Specific MCP Server​

Limit your agent to tools from one MCP server.

  1. In the "MCP Source" section, select "Use specific bundle" (one MCP server)
  2. Choose an MCP server from the dropdown
  3. Your agent can only use tools from that MCP server

Best for: Focused A2A agents that work with one service (e.g., "GitHub Monitor" using only GitHub tools)

MCP server must be operational

If you choose a specific MCP server, it must be enabled and have all required credentials verified. If the MCP server becomes unavailable, your A2A agent will be automatically paused.

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​

The heartbeat checklist is what your A2A agent runs on each scheduled execution.

  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 execute this checklist every time it runs.

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 your A2A agent can run, make sure:

  • ✅ Agent Instructions are saved
  • ✅ Heartbeat Checklist is saved

Then click "Activate" to start your agent.

Once activated, your A2A agent will run automatically on the schedule 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 checklist right away
  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.

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 or Hub 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)
  • Heartbeat Checklist is saved (not empty)
  • 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 or heartbeat checklist
  • 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 or Hub
  • 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 (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.