Agent Doorbell

Start here

Set up your first agent

Choose events, test the connection, and review your setup before going live.

When to use it

Start with one agent and one event source. You can add more sources or result outputs later.

Example

An order webhook sends order.status set to needs_review. A sample confirms the rule matches. After your agent acknowledges a connection test, activate order-reviewer and send a new order.

Set it up

  1. Sign in with your invited email address and choose Set up an agent. Name an agent you own and run.
  2. Choose an MCP connection or a webhook receiver. For MCP, follow Connect your agent to add Doorbell to your agent's client.
  3. Select email, Slack, Teams, a webhook, or agent messages. Choose fields to share and add any conditions. To receive only direct agent messages, continue without an input.
  4. Save the draft. Preview a sample that should match and one that should not. Check the fields you plan to share. Previews do not store samples or notify your agent.
  5. Approve and send a connection test. For MCP, ask your agent to receive and acknowledge it, then check the test status. Tests must not start real tasks or replies.
  6. Review the receiver, rules, shared fields, and any storage changes. Approve these settings and choose Activate.
  7. Send a new matching event and check delivery. Also try an event that should not match. Check task results in your agent's workflow.

Important limits

  • Saving does not test or activate your setup. When you edit a live setup, its active settings stay in effect until you activate the changes.
  • Storage changes apply to every workflow using that source, not just this agent. They take effect on activation.
  • An MCP test passes only after the receiving agent acknowledges it. Adding a test to the inbox is not enough.
  • Activation starts with future events. It does not replay old events or missed mail. Your agent needs its own tools and permission to read email bodies.

Troubleshooting

  • If your activation review expires, refresh it and approve the settings again. Repeat the connection test only if the current receiver no longer has a valid test.
  • If your agent has no webhook URL and key, use MCP only if it can keep checking for messages. Doorbell cannot wake a sleeping agent.
Technical reference

Agent-led setup uses save_agent_address, test_agent_receiver, and activate_agent_address. Each action requires your approval and approved: true. Check list_agent_addresses before creating another agent or output.

save_agent_address accepts name and optional kind, receiver, inputs, notifications, samples, and expectedRevision. Each input has source: {family,instanceId}, when, include, and optional capture. Notifications contains grouping, pageSize, and overflowMode. A new agent defaults to an MCP receiver with no external inputs. An output uses kind: output and an approved webhook receiver.

Use the same source-relative paths in when and include, such as order.status and order.id, or topic and text. Pass matching and nonmatching samples as [{inputIndex,sample}]. Save returns address, previews, confirmation, expiresAt, and blockers. Each preview contains inputIndex, matches, event, and include.

Omitted edit fields keep their saved values. Configuration changes require the current expectedRevision. Changing only samples does not change the revision. Omitting capture keeps the source's stored-field settings.

Save and sample previews require configuration:write, including when settings are unchanged. They do not create retained messages or invoke receivers. Agents with empty inputs need no sample preview.

For an MCP test, call receive_agent_message with address, a stable holder, and receiver: draft. Check synthetic and acknowledge the returned leaseId with ack_mcp_wakeup. Then call activate_agent_address with name and the confirmation from save, without revision. The receiver acknowledgment keeps that confirmation valid.

After activation, use send_agent_message for direct messages. Acknowledge live messages after durable handling or handoff. Match message and signal IDs with list_agent_addresses. Pause or delete through pause_agent_address or delete_agent_address with the observed expectedRevision and approved: true. Pause preserves capture and messages; deletion removes the address's memberships and notification history, not canonical messages or shared webhook receivers.

Open Agent Doorbell