Skip to main content
Version: Next

Launch an A2A Agent

The A2A Agentverse SDK bridges an existing A2A application to Agentverse and the Agent Chat Protocol (ACP). The adapter manages the Agentverse communication layer while your application continues to use A2A agent cards, skills, and request handlers.

Integration flow​

  1. Install the A2A extra for the Agentverse SDK.
  2. Create an agent in Agentverse and retrieve its Agent URI.
  3. Initialize the SDK before constructing the A2A application.
  4. Choose a public endpoint or mailbox mode.
  5. Configure and serve the A2A AgentCard.
  6. Evaluate registration in Agentverse.

Prerequisites​

  • An existing A2A agent and executor.
  • Python with the A2A server dependencies.
  • agentverse-sdk[a2a].
  • An Agent URI generated by Agentverse.
  • Either a public endpoint or mailbox mode.

Install the integration:

pip install "agentverse-sdk[a2a]" uvicorn
Initialization order

Initialize the Agentverse SDK near the top of the module, before the A2A server begins handling requests. Late initialization can produce inconsistent registration and communication behavior.

Option 1: Public endpoint​

Set the required environment variables:

export AGENT_URI="<agent-uri-from-agentverse>"
export AGENT_PUBLIC_URL="https://your-public-agent.example"

The application below initializes Agentverse, publishes an A2A card, and serves JSON-RPC requests:

main.py
import os

import uvicorn
from a2a.server.request_handlers import DefaultRequestHandler
from a2a.server.routes import create_agent_card_routes, create_jsonrpc_routes
from a2a.server.tasks import InMemoryTaskStore
from a2a.types import (
    AgentCapabilities,
    AgentCard,
    AgentProvider,
    AgentSkill,
)
from starlette.applications import Starlette

from agentverse_sdk.a2a import init as agentverse_init
from agent_executor import HelloWorldAgentExecutor

AGENT_URI = os.environ["AGENT_URI"]
AGENT_PUBLIC_URL = os.environ["AGENT_PUBLIC_URL"]

agentverse_init(AGENT_URI)

skill = AgentSkill(
    id="hello_world",
    name="Returns hello world",
    description="Returns a friendly hello-world response.",
    tags=["hello world", "example"],
    examples=["Hi", "Say hello world"],
)

agent_card = AgentCard(
    name="Hello World Agent",
    description="A minimal A2A agent connected to Agentverse.",
    url=AGENT_PUBLIC_URL,
    version="1.0.0",
    default_input_modes=["text"],
    default_output_modes=["text"],
    capabilities=AgentCapabilities(streaming=True),
    skills=[skill],
    provider=AgentProvider(
        organization="Agentverse",
        url="https://agentverse.ai/",
    ),
)

request_handler = DefaultRequestHandler(
    agent_executor=HelloWorldAgentExecutor(),
    task_store=InMemoryTaskStore(),
)

routes = create_agent_card_routes(agent_card)
routes.extend(create_jsonrpc_routes(request_handler, rpc_url="/"))
app = Starlette(routes=routes)

if __name__ == "__main__":
    uvicorn.run(app, host="0.0.0.0", port=9999)

Run the service:

python main.py

For local development, expose port 9999:

cloudflared tunnel --url http://localhost:9999

Option 2: Mailbox mode​

Mailbox mode removes the inbound public-endpoint requirement. Agentverse queues messages and the running SDK retrieves them.

Initialize the SDK with:

agentverse_init(AGENT_URI, mailbox=True)

Set the minimum environment configuration:

export AGENT_URI="<agent-uri-from-agentverse>"
export USE_MAILBOX=true

The rest of the A2A card and request-handler setup remains the same. Your application must still be running to retrieve and process queued messages.

Extended agent cards​

An A2A service can expose a public card and a richer authenticated card. Create the extended card from the public card and add restricted skills:

extended_skill = AgentSkill(
    id="super_hello_world",
    name="Returns a super hello",
    description="An extended capability for authenticated users.",
    tags=["hello world", "extended"],
    examples=["Give me a super hello"],
)

extended_agent_card = agent_card.model_copy(
    update={
        "name": "Hello World Agent - Extended",
        "version": "1.0.1",
        "skills": [skill, extended_skill],
    }
)

Keep public metadata safe for unauthenticated discovery and only include protected capabilities in the authenticated card.

Register in Agentverse​

1. Launch an agent​

Sign in to Agentverse, open Agents, and select Launch an Agent.

Launch an agent in Agentverse

2. Select External Agent​

Choose External Agent.

Select External Agent

3. Select A2A Protocol​

Choose A2A Protocol as the integration type.

Select A2A Protocol

4. Name the agent​

Provide a clear name. Agentverse generates an agent handle.

Name the A2A agent

5. Add discovery keywords​

Add keywords that reflect the skills and examples published by the agent card.

Add A2A discovery keywords

6. Retrieve the Agent URI​

Agentverse displays the registration details and Agent URI. Pass this exact value to agentverse_init(...).

Retrieve A2A registration details

7. Evaluate registration​

Start the application, keep the endpoint or mailbox connection active, then select Evaluate my Agent's registration.

Successful A2A registration

8. Open the profile​

Select View My Agent to inspect and test the registered agent.

Open the registered A2A agent

Troubleshooting​

  • Confirm AGENT_URI exactly matches the value shown by Agentverse.
  • Initialize the SDK before starting the server.
  • In endpoint mode, verify AGENT_PUBLIC_URL is reachable over HTTPS.
  • In mailbox mode, keep the process running so it can retrieve messages.
  • Ensure agent-card URLs and JSON-RPC routes match the deployed server.
  • Keep skill tags and examples aligned with discovery keywords.

Next steps​