Introduction

The A2A (Agent-to-Agent) protocol solves the multi-agent workflow problem—how agents delegate tasks, share context, and coordinate responses. But there's a prerequisite: how do agents find each other in the first place?

That's where agent discovery comes in. Agent discovery is the standard mechanism that allows AI agents to advertise their capabilities and locate other agents across the internet. Think of it like DNS for agents, or the .well-known/openid-configuration file used in OAuth—a predictable endpoint where agents publish their "business card."

The standard file is called .well-known/agent.json. When Agent A wants to communicate with Agent B:

Agent A queries https://agentB.com/.well-known/agent.json
Gets back Agent B's capabilities (what skills it offers, what protocols it supports, authentication methods)
Uses that information to send properly formatted task requests

By the end of this guide, you'll have:

Your MoltFlow agent(s) discoverable via agent.json
External agents registered in your MoltFlow instance
Secure authentication between agents

This unlocks powerful integrations—CRM agents, payment processor agents, specialized industry agents from marketplaces—all working together seamlessly.

What You'll Need

MoltFlow account with A2A protocol enabled (available on Business and Enterprise plans)
Domain with HTTPS (required for hosting .well-known/agent.json—agent discovery requires secure connections)
Understanding of A2A protocol basics (if you're new, read How to Set Up Multi-Agent Workflows with A2A Protocol first)
Optional: API key or authentication credentials for external agents you want to connect

Important: Agent discovery is for production integrations. If you're just testing multi-agent workflows internally, you don't need agent discovery—MoltFlow agents can communicate directly without the .well-known/agent.json step.

Step 1: Understand Agent Discovery

Agent discovery solves the "cold start" problem. Without a discovery standard, Agent A needs to know:

Where is Agent B's endpoint? (https://agentB.com/api/tasks? /v1/a2a? Something else?)
What skills does Agent B offer? (Is it a billing expert? A translation service? A data analyst?)
What input format does Agent B expect? (JSON? XML? Custom schema?)
How do I authenticate? (API key? OAuth? Mutual TLS?)

With .well-known/agent.json, all of this information is published at a standard location. Agent A just needs Agent B's domain.

The .well-known/agent.json File

Here's what a typical agent.json looks like:

json

{
  "agent": {
    "name": "MoltFlow Billing Agent",
    "version": "1.0",
    "description": "Specialized agent for billing inquiries, invoice lookup, and refund processing",
    "provider": "MoltFlow",
    "homepage": "https://molt.waiflow.app",
    "capabilities": {
      "skills": [
        "answer_billing_question",
        "lookup_invoice",
        "process_refund",
        "update_payment_method"
      ],
      "languages": ["en", "es", "fr"],
      "max_concurrent_tasks": 50,
      "avg_response_time_ms": 1200
    },
    "endpoints": {
      "task_request": "https://apiv2.waiflow.app/a2a/tasks",
      "task_status": "https://apiv2.waiflow.app/a2a/tasks/{task_id}/status",
      "health": "https://apiv2.waiflow.app/a2a/health"
    },
    "protocols": {
      "a2a": {
        "version": "1.2",
        "supported_task_types": [
          "answer_question",
          "query_data",
          "execute_action"
        ]
      }
    },
    "authentication": {
      "methods": ["api_key", "hmac_sha256"],
      "api_key": {
        "header": "X-API-Key",
        "required_scopes": ["tasks:execute"]
      },
      "hmac": {
        "algorithm": "sha256",
        "header": "X-Signature"
      }
    },
    "rate_limits": {
      "requests_per_minute": 100,
      "burst": 20
    },
    "contact": {
      "email": "[email protected]",
      "support_url": "https://molt.waiflow.app/help"
    }
  }
}

Key Fields Explained:

name: Human-readable agent name
capabilities.skills: Array of task types this agent can handle (these are your "menu items" that other agents can request)
endpoints.task_request: The URL where other agents send task requests
protocols.a2a.version: Which A2A protocol version this agent implements
authentication.methods: How other agents should authenticate (API key, HMAC signature, etc.)
rate_limits: How many requests per minute this agent accepts

When an external agent wants to delegate a task to your MoltFlow agent, it fetches this file, validates the capabilities match what's needed, and then sends a task request to the endpoints.task_request URL.

Step 2: Configure Your MoltFlow Agent Card

Before you can publish agent.json, you need to define what your agent offers. In MoltFlow, this is called an "agent card."

Go to AI Config → [Select Your Agent] → Agent Card Settings:

1. Define Skills

List the task types your agent can handle. Be specific—these become the capabilities.skills in your agent.json.

Example for a billing agent:

text

- answer_billing_question
- lookup_invoice
- process_refund
- update_payment_method
- check_subscription_status

Example for a support agent:

text

- answer_product_question
- troubleshoot_technical_issue
- create_support_ticket
- escalate_to_human

2. Define Input/Output Schemas

Other agents need to know what data format you expect. Define schemas for each skill.

Example schema for answer_billing_question:

json

{
  "input": {
    "type": "object",
    "properties": {
      "question": {"type": "string", "required": true},
      "customer_id": {"type": "string", "required": true},
      "conversation_history": {"type": "array", "items": {"type": "string"}}
    }
  },
  "output": {
    "type": "object",
    "properties": {
      "answer": {"type": "string", "required": true},
      "confidence": {"type": "number", "min": 0, "max": 1, "required": true},
      "invoice_references": {"type": "array", "items": {"type": "string"}}
    }
  }
}

3. Set Rate Limits

How many task requests per minute can your agent handle? Set realistic limits based on your plan and infrastructure.

Example settings:

Requests per minute: 100 (for Business plan)
Burst: 20 (allows short spikes)
Max concurrent tasks: 50

4. Configure Languages

Which languages does your agent support? List them as ISO language codes.

Example: ["en", "es", "fr"] for English, Spanish, French.

5. Add Contact Information

Provide support contact details in case external agents encounter issues.

Example:

Email: [email protected]
Support URL: https://yourdomain.com/agent-support

Save the agent card. MoltFlow will use this configuration to generate your agent.json file.

Step 3: Publish Your agent.json Endpoint

MoltFlow auto-generates your .well-known/agent.json file based on your agent card configuration. You just need to make it accessible at the right URL.

Option A: Host on Your Domain (Recommended)

If you have a custom domain (e.g., yourdomain.com), set up a reverse proxy or CDN rule to serve the agent.json file:

1. Get your generated agent.json:

Go to AI Config → [Your Agent] → Agent Card → Download agent.json
MoltFlow generates the file based on your configuration from Step 2

2. Upload to your web server:

Place the file at: https://yourdomain.com/.well-known/agent.json
Ensure it's publicly accessible (no authentication required for discovery)

3. Set CORS headers (required for browser-based agent clients):

text

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, OPTIONS
Access-Control-Allow-Headers: Content-Type

4. Test accessibility:

bash

curl https://yourdomain.com/.well-known/agent.json

You should see your agent card JSON. If you get a 404, check your web server configuration.

Option B: Use MoltFlow's Hosted Discovery (Simpler)

If you don't have a custom domain, MoltFlow can host your agent.json at a subdomain:

1. Go to AI Config → [Your Agent] → Agent Discovery → Enable Hosted Discovery

2. Choose a subdomain:

MoltFlow offers: your-agent-name.agents.waiflow.app
Example: billing-agent.agents.waiflow.app

3. MoltFlow auto-publishes:

Your agent.json is immediately available at: https://billing-agent.agents.waiflow.app/.well-known/agent.json
No manual upload required
Updates automatically when you modify your agent card

4. Test:

bash

curl https://billing-agent.agents.waiflow.app/.well-known/agent.json

Important: If you use hosted discovery, share the full subdomain URL with other agents (e.g., billing-agent.agents.waiflow.app, not just waiflow.app).

Validation

Use MoltFlow's built-in validator:

Go to AI Config → [Your Agent] → Agent Discovery → Validate
MoltFlow fetches your published agent.json and checks for:
- Valid JSON format
- Required fields present
- HTTPS enabled
- CORS headers configured
- A2A protocol version compatibility

Fix any errors before moving to the next step.

Step 4: Register External Agents

Now that your agent is discoverable, let's register external agents so your MoltFlow instance can delegate tasks to them.

Go to AI Config → External Agents → Register New Agent:

1. Enter the Discovery URL

Provide the base domain of the external agent. MoltFlow will automatically fetch .well-known/agent.json.

Example: https://external-agent.com

MoltFlow makes a request to: https://external-agent.com/.well-known/agent.json

2. Review Capabilities

MoltFlow displays the agent's capabilities (skills, input/output formats, rate limits). Verify these match what you need.

Example display:

text

Agent Name: CRM Contact Enrichment Agent
Skills:
  - enrich_contact_data
  - validate_email
  - lookup_company_info

Rate Limits: 50 requests/minute
Authentication: API key required (header: X-API-Key)

3. Assign Trust Level

Choose a trust level for this external agent (see How to Create an A2A Content Policy for Safe Agent Communication for guidance):

None: Newly registered, untested
Basic: Verified provider, limited data access
Standard: Trusted partner, broader data access
Full: Only for agents you fully control (not recommended for external agents)

Start with "None" or "Basic" until you've tested the integration.

4. Configure Authentication

If the external agent requires authentication (most do), provide credentials:

For API key authentication:

Header name: X-API-Key (check the agent's documentation)
API key value: [Paste your key from the external provider]

For HMAC authentication:

Shared secret: [Paste the secret provided by the external agent]
Algorithm: SHA-256 (or as specified in agent.json)

5. Save

MoltFlow validates the connection by making a test request to the agent's health endpoint. If successful, the agent is registered and ready to receive task delegations.

Step 5: Set Up Secure Agent Handshakes

Authentication between agents ensures that task requests are legitimate and not from malicious actors.

For Your MoltFlow Agent (Receiving Task Requests)

Configure which authentication methods you accept:

Go to AI Config → [Your Agent] → Security → Authentication:

Enable API Key Authentication:

Check "Require API Key"
Generate a key: moltflow_live_a2a_1234abcd5678efgh
Share this key with external agents that want to send you task requests
Set scopes: ["tasks:execute", "tasks:status"]

Enable HMAC Signature Authentication (more secure):

Check "Require HMAC Signature"
Generate a shared secret: your-secret-key-keep-this-safe
Share the secret with external agents
Algorithm: SHA-256
Header: X-Signature

How HMAC works:

External agent constructs the task request body
Computes HMAC: HMAC-SHA256(request_body, shared_secret)
Includes the signature in the X-Signature header
Your MoltFlow agent verifies the signature matches before processing the request

Example HMAC signature generation (Python):

python

import hmac
import hashlib

request_body = '{"task_type": "answer_question", "input": {...}}'
shared_secret = "your-secret-key-keep-this-safe"

signature = hmac.new(
    shared_secret.encode(),
    request_body.encode(),
    hashlib.sha256
).hexdigest()

headers = {
    "X-Signature": signature,
    "Content-Type": "application/json"
}

For External Agents (Sending Task Requests)

When you register an external agent in Step 4, you provided its authentication credentials. MoltFlow automatically includes these in task requests.

Verify it's working:

Send a test task to the external agent (see Step 6)
Check the agent's logs to confirm authentication passed
If you see 401/403 errors, double-check the API key or HMAC secret

Security Best Practices

1. Rotate keys regularly: Change API keys and HMAC secrets every 90 days 2. Use HMAC for production: API keys are simpler but HMAC prevents replay attacks 3. Restrict scopes: Only grant the minimum scopes needed (e.g., tasks:execute but not admin:full_access) 4. Monitor for suspicious activity: Set up alerts for repeated authentication failures 5. Use HTTPS everywhere: Agent discovery and task requests must use secure connections

Step 6: Test Discovery and Connectivity

Time to verify everything works end-to-end.

Test 1: Verify Your Agent is Discoverable

From an external machine (not your MoltFlow instance), fetch your agent.json:

bash

curl https://yourdomain.com/.well-known/agent.json

Expected: JSON response with your agent card (name, capabilities, endpoints, authentication).

If you get 404: Check that the file is at the correct path (.well-known/agent.json, not well-known/agent.json or .well_known/agent.json).

Test 2: Discover External Agent

In MoltFlow's agent registry, test discovery:

Go to AI Config → External Agents → [Your Registered Agent] → Test Discovery

MoltFlow re-fetches the agent.json and displays the result. Verify capabilities match what you expect.

Test 3: Send Test Task Request

Send a test task to the external agent:

Go to AI Config → External Agents → [Agent] → Test Connection

Configure a test task:

json

{
  "task_type": "enrich_contact_data",
  "input": {
    "email": "[email protected]"
  }
}

Expected response:

json

{
  "status": "success",
  "output": {
    "email": "[email protected]",
    "company": "Example Corp",
    "job_title": "Marketing Manager",
    "linkedin_url": "https://linkedin.com/in/test"
  },
  "confidence": 0.92
}

If you get errors:

401 Unauthorized: Authentication failed—check API key or HMAC secret
404 Not Found: Endpoint URL is wrong—verify agent.json has correct endpoints.task_request
422 Unprocessable Entity: Input schema mismatch—check what the agent expects
Timeout: Agent is slow or down—check rate limits, try again

Test 4: Verify Agent Can Call You

Have an external agent send a test task to your MoltFlow agent:

Option A: Use MoltFlow's Test Tool

Go to AI Config → [Your Agent] → Incoming Test
MoltFlow simulates an external agent sending a task request
Verify your agent processes it correctly

Option B: Use the External Agent's Test Interface

Most external agents have a "Test Task" feature
Send a task to your endpoints.task_request URL
Check MoltFlow logs to confirm it was received and processed

If authentication fails: Double-check the API key or HMAC secret you shared with the external agent.

Troubleshooting Common Issues

Issue 1: CORS Error in Browser-Based Agents

Symptom: Browser console shows "CORS policy blocked"
Fix: Add CORS headers to your agent.json endpoint (see Step 3)

Issue 2: SSL Certificate Error

Symptom: Agent discovery fails with "SSL certificate verification failed"
Fix: Ensure your domain has a valid SSL certificate (not self-signed). Use Let's Encrypt for free certs.

Issue 3: Agent.json Not Found (404)

Symptom: curl https://yourdomain.com/.well-known/agent.json returns 404
Fix: Verify the path is exactly .well-known/agent.json (note the leading dot). Check web server config (Nginx, Apache, CDN rules).

Issue 4: Capability Mismatch

Symptom: Task fails with "skill not supported"
Fix: Re-fetch the external agent's agent.json (capabilities may have changed). Verify the task type you're requesting matches a skill in the capabilities.skills array.

Issue 5: Rate Limit Exceeded

Symptom: Task fails with "429 Too Many Requests"
Fix: Check rate_limits.requests_per_minute in the agent's agent.json. Reduce your request rate or contact the agent provider to increase limits.

What's Next

You've set up agent discovery and connected external agents to MoltFlow. Here are recommended next steps:

Build multi-agent workflows: Use your newly registered external agents in delegation workflows—see How to Set Up Multi-Agent Workflows with A2A Protocol
Secure your agents: Add content policies and trust levels—read How to Create an A2A Content Policy for Safe Agent Communication
Explore the agent marketplace: Discover pre-built specialist agents at OpenClaw Agent Hub for CRM, analytics, payments, and more
Monitor performance: Track task success rates, response times, and authentication failures in your dashboard

Agent discovery transforms isolated AI agents into a connected ecosystem. Start with one or two external integrations, learn what works, and expand from there. The A2A standard ensures compatibility across providers—your workflows are portable and future-proof.

How to Connect External AI Agents to MoltFlow via Agent Discovery

Introduction

What You'll Need

Step 1: Understand Agent Discovery

The .well-known/agent.json File

Step 2: Configure Your MoltFlow Agent Card

Step 3: Publish Your agent.json Endpoint

Option A: Host on Your Domain (Recommended)

Option B: Use MoltFlow's Hosted Discovery (Simpler)

Validation

Step 4: Register External Agents

Step 5: Set Up Secure Agent Handshakes

For Your MoltFlow Agent (Receiving Task Requests)

For External Agents (Sending Task Requests)

Security Best Practices

Step 6: Test Discovery and Connectivity

Test 1: Verify Your Agent is Discoverable

Test 2: Discover External Agent

Test 3: Send Test Task Request

Test 4: Verify Agent Can Call You

Troubleshooting Common Issues

What's Next

Ready to automate your WhatsApp?