From 78ed015312ccaf62562663c41e8d88f7e40a5deb Mon Sep 17 00:00:00 2001 From: ypeng Date: Mon, 1 Jun 2026 09:30:58 -0700 Subject: [PATCH] Fix A2A documentation URLs and deployment base URL guidance. Update protocol links, replace App Platform examples with agents.do-ai.run endpoints, and clarify how A2A_BASE_URL relates to the /run invoke URL. Co-authored-by: Cursor --- README.md | 56 ++++++++++++++++++++++++++++++------------ examples/a2a/server.py | 4 +-- 2 files changed, 42 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index 8eb119a..a9b2935 100644 --- a/README.md +++ b/README.md @@ -324,8 +324,8 @@ export GRADIENT_MODEL_ACCESS_KEY=your_gradient_key # Optional: Enable verbose trace logging export GRADIENT_VERBOSE=1 -# Optional: A2A protocol — base URL for AgentCard discovery -export A2A_BASE_URL=https://your-app.ondigitalocean.app +# Optional: A2A — deployment base URL (invoke URL with trailing /run removed) +export A2A_BASE_URL=https://agents.do-ai.run// ``` ## Project Structure @@ -380,7 +380,7 @@ The ADK is designed to work with any Python-based AI agent framework: ## A2A Protocol Support -The ADK supports the [Agent-to-Agent (A2A) protocol v0.3.0](https://github.com/google/A2A), enabling any `@entrypoint` agent to communicate with A2A-compatible clients. Install with `pip install gradient-adk[a2a]`. +The ADK supports the [Agent-to-Agent (A2A) protocol v0.3.0](https://a2a-protocol.org/v0.3.0/specification/) ([protocol repository](https://github.com/a2aproject/A2A)), enabling any `@entrypoint` agent to communicate with A2A-compatible clients. Install with `pip install gradient-adk[a2a]`. ### Wrapping an Agent with A2A @@ -425,17 +425,39 @@ Client Server └── POST / tasks/cancel ──────────────► Best-effort cancellation ``` -### Deploying to DigitalOcean App Platform +### Configuring the public URL -When you deploy to App Platform, the public URL is assigned after deployment. The A2A server needs this URL for the AgentCard so that clients know where to send requests. The workflow is: +Deployed agents expose two related URLs on `agents.do-ai.run`: -1. **Deploy your agent** to App Platform as usual with `gradient agent deploy` -2. **Get your app's public URL** from the App Platform dashboard (e.g., `https://your-agent-abc123.ondigitalocean.app`) -3. **Set the environment variable** in your app's settings: - ```bash - A2A_BASE_URL=https://your-agent-abc123.ondigitalocean.app - ``` -4. **Redeploy** — the agent restarts and the AgentCard now advertises the correct public URL +| Purpose | URL | HTTP | +| --- | --- | --- | +| Gradient invoke (`@entrypoint`) | `https://agents.do-ai.run///run` | `POST` with `{"prompt": "..."}` | +| A2A discovery | `https://agents.do-ai.run///.well-known/agent-card.json` | `GET` | +| A2A JSON-RPC | `https://agents.do-ai.run///` | `POST` (`message/send`, `tasks/get`, …) | + +Example invoke URL: + +``` +https://agents.do-ai.run/00f7470e-1310-49ef-baea-0addf60a6594/test-deploy/run +``` + +Set `A2A_BASE_URL` to the invoke URL **without** the trailing `/run`. That value is written to the AgentCard `url` field and is where clients send JSON-RPC requests (not the `/run` endpoint): + +```bash +# From: .../test-deploy/run → A2A_BASE_URL: .../test-deploy +export A2A_BASE_URL=https://agents.do-ai.run/00f7470e-1310-49ef-baea-0addf60a6594/test-deploy +``` + +After `gradient agent deploy`, remove `/run` from the printed invoke URL to get `A2A_BASE_URL` (the CLI may include a `/v1/` segment in the path — keep it when stripping `/run`). + +You can also pass `base_url` when creating the server: + +```python +app = create_a2a_server( + my_agent, + base_url="https://agents.do-ai.run/00f7470e-1310-49ef-baea-0addf60a6594/test-deploy", +) +``` For local development, no configuration is needed — it defaults to `http://localhost:8000`. @@ -446,9 +468,11 @@ Once deployed, any A2A-compatible agent or client can call your agent: ```python import httpx -# Discover the remote agent -card = httpx.get("https://your-agent.ondigitalocean.app/.well-known/agent-card.json").json() -rpc_url = card["url"] +# Discover the remote agent (base URL = invoke URL without /run) +invoke_url = "https://agents.do-ai.run/00f7470e-1310-49ef-baea-0addf60a6594/test-deploy/run" +agent_base = invoke_url.removesuffix("/run") +card = httpx.get(f"{agent_base}/.well-known/agent-card.json").json() +rpc_url = card["url"] # same as agent_base when A2A_BASE_URL is set correctly # Send a message response = httpx.post(rpc_url, json={ @@ -473,7 +497,7 @@ result = httpx.post(rpc_url, json={ }).json()["result"] ``` -See `examples/a2a/client.py` for a complete async client with discovery, send, poll, and cancel. +See [examples/a2a/client.py](https://github.com/digitalocean/gradient-adk/blob/main/examples/a2a/client.py) for a complete async client with discovery, send, poll, and cancel. ### Supported Operations diff --git a/examples/a2a/server.py b/examples/a2a/server.py index 8571502..b8baed5 100644 --- a/examples/a2a/server.py +++ b/examples/a2a/server.py @@ -6,8 +6,8 @@ To run this agent: 1. Ensure you have gradient-adk and a2a-sdk installed: pip install gradient-adk[a2a] -2. Set the base URL for discovery (optional, defaults to localhost for dev): - export A2A_BASE_URL=https://your-app.ondigitalocean.app +2. When deployed, set the A2A base URL (invoke URL without /run; optional for local dev): + export A2A_BASE_URL=https://agents.do-ai.run// 3. Run: gradient agent run 4. The agent will be available with both Gradient and A2A protocols """