Agent Executor (AX) is Google's open agentic orchestration runtime
Go
Add documentation for a2a agent. (#337)
Junjie Wang370c658d467d
diff --git a/README.md b/README.mdindex 0c1e2c9..8cb1f9c 100644--- a/README.md+++ b/README.md@@ -133,7 +133,9 @@ ax exec \### 2. Execute with Custom AgentsMost developers want to build their own agents. AX allows running custom agents as remote-or sandbox agents. This example demonstrates how the AX server executes remote agents+or sandbox agents. See [Custom Agents](#custom-agents) for a full list of supported agents.++This example demonstrates how the AX server executes remote agentsthrough the `AgentService.Connect` RPC.**Terminal 1** - Start the remote agent server:@@ -356,15 +358,25 @@ requires explicit user approval via a confirmation flow before running.### Custom Agents-Custom agents can be registered on the AX server:+AX supports multiple ways to bring your own agents into the runtime.++#### Remote agents++Remote agents run outside the AX controller and are invoked over a protocol boundary.++- [Remote Agent](examples/remote_agent): implement AX's native `AgentService` directly.+- [ADK Agent (Python)](examples/adk_agent): run a Google ADK agent behind the AX gRPC wrapper so it can be registered as a remote agent.+- [A2A Agent](examples/a2a_agent): connect agents that speak the [A2A protocol](https://github.com/a2aproject/A2A) through AX's A2A bridge.++#### Sandboxed agents++Sandboxed agents execute user-provided code in an external execution environment managed by AX.++- [Colab Agents](examples/colab_agent)(experimental): run Python scripts or notebooks in a remote Google Colab session.-- [Remote Agent](examples/remote_agent)-- [ADK Agent (Python Example)](examples/adk_agent)-- [Colab Agents (Experimental)](examples/colab_agent)+Please note that AX is actively developing its resumable streaming and agent communication protocols; these interfaces may change before a stable release.-Please note that AX is actively developing a resumable streaming protocol;-as a result, the server-to-agent communication protocol will undergo significant revisions.-See the `AgentService` in `proto/ax.proto` to implement remote agents.+If you are implementing an AX-native remote agent, see `AgentService` in `proto/ax.proto`.## What AX is NOT?* A managed service. AX is self-hosted and not a managed service.diff --git a/examples/a2a_agent/README.md b/examples/a2a_agent/README.mdnew file mode 100644index 0000000..d5e41be--- /dev/null+++ b/examples/a2a_agent/README.md@@ -0,0 +1,110 @@+# A2A Agent++`coding_agent.py` is a sample [A2A-protocol](https://github.com/a2aproject/A2A)+agent built on Google ADK's `LlmAgent` (Gemini). It demonstrates how to+register and use any A2A-compliant agent from AX.++The agent writes Python code on request, asks the user to confirm a save+path before writing anything, and returns the saved source as a file+attachment.++## What it demonstrates++- **The full A2A integration surface AX supports**: AgentCard discovery,+ multi-transport (gRPC + JSON-RPC + HTTP+JSON REST), streaming and+ polling-fallback, FilePart artifacts.+- **HITL via A2A's `TASK_STATE_INPUT_REQUIRED`** mapped to AX's+ `ConfirmationContent`. The agent proposes a path; AX prompts the+ user; the user's "yes" reply resumes the same A2A task.+- **Optional dual-scheme auth** (`--auth`): the AgentCard advertises+ Bearer and API-key as alternatives; the server enforces either via+ HTTP middleware and a gRPC interceptor.++## Prerequisites++- Python 3.10+ and [`uv`](https://docs.astral.sh/uv/) (the script uses+ PEP-723 inline metadata to declare its dependencies)+- Gemini credentials set in the environment:+ ```bash+ # Either a Gemini API key:+ export GOOGLE_API_KEY="<your-key>"++ # OR Vertex AI (requires gcloud application-default credentials):+ export GOOGLE_GENAI_USE_VERTEXAI=TRUE+ export GOOGLE_CLOUD_PROJECT="<your-project>"+ export GOOGLE_CLOUD_LOCATION="<your-region>"+ ```++## Run the agent server++```bash+# From ax root directory+uv run examples/a2a_agent/coding_agent.py+```++This serves:++- HTTP / JSON-RPC / REST on `127.0.0.1:41241`+- gRPC on `127.0.0.1:50051`+- AgentCard at `http://127.0.0.1:41241/.well-known/agent-card.json`++### Useful flags++| Flag | Purpose |+|---|---|+| `--host`, `--port`, `--grpc-port` | Override default listen addresses. |+| `--no-streaming` | Disable streaming in the AgentCard so clients exercise the polling fallback. |+| `--auth` | Enable auth (advertises both Bearer and API key on the card; accepts either). Requires the env var named by `--auth-token-env`. |+| `--auth-token-env` | Env var that holds the expected credential value. Default: `CODING_AGENT_AUTH_TOKEN`. |+| `--api-key-header` | Header name advertised on the AgentCard's `APIKeySecurityScheme.name`. Default: `X-API-Key`. |+| `--log-level` | `DEBUG`, `INFO`, `WARNING`, `ERROR`. Default: `INFO`. |++## Register the agent in AX++Add an entry under `registry.remote_agents` in your `ax.yaml`:++```yaml+registry:+ remote_agents:+ - id: "coding-agent"+ name: "Coding Agent"+ description: "Writes Python code and saves it to disk after the user confirms a path."+ address: "http://127.0.0.1:41241"+ protocol: "a2a"+```++To use the auth flow, also set the credential and add an `auth` block:++```yaml+registry:+ remote_agents:+ - id: "coding-agent"+ name: "Coding Agent"+ description: "Writes Python code and saves it to disk after the user confirms a path."+ address: "http://127.0.0.1:41241"+ protocol: "a2a"+ auth:+ type: "bearer" # or "api_key"+ credential_env: "CODING_AGENT_AUTH_TOKEN"+```++Make sure both AX's process and the agent process see the same value+for `CODING_AGENT_AUTH_TOKEN`.++## Try it++Start the agent server in one terminal, then in another:++```bash+ax exec --input "Write me a Python flask hello-world server."+```++The planner delegates to `coding-agent`, which:++1. Generates the code+2. Proposes a save path (e.g. `~/flask_app.py`) and pauses for confirmation+3. AX prompts you `Confirm? [yes/no]`+4. On `yes`, the agent writes the file and returns the source as a+ `text/x-python` FilePart alongside its text reply+5. On `no`, the agent emits the proposed code as a fenced markdown block+ instead and skips the write