[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-82468":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":17,"stars7d":18,"stars30d":19,"stars90d":16,"forks30d":16,"starsTrendScore":20,"compositeScore":21,"rankGlobal":10,"rankLanguage":10,"license":22,"archived":23,"fork":23,"defaultBranch":24,"hasWiki":23,"hasPages":23,"topics":25,"createdAt":10,"pushedAt":10,"updatedAt":26,"readmeContent":27,"aiSummary":28,"trendingCount":16,"starSnapshotCount":16,"syncStatus":29,"lastSyncTime":30,"discoverSource":31},82468,"ax","google\u002Fax","google","Google's open source distributed agent runtime","https:\u002F\u002Fagentexecutor.io",null,"Go",1637,90,16,24,0,53,290,318,159,103.88,"Apache License 2.0",false,"main",[],"2026-06-12 04:01:38","# Agent Executor (AX)\n\n> [!WARNING]\n> 🚧 **AX is in active early development.**\n>\n> We are actively refining our core, resumption protocols,\n> and runtime specifications, which will introduce major breaking\n> changes prior to a stable release.\n>\n> **Temporary Policy:** We are temporarily pausing the acceptance of external Pull Requests while we stabilize the core architecture. We warmly encourage you to open Issues for feedback and feature requests instead.\n>\n> We will announce this project\n> widely soon. If you are interested in collaborating with us,\n> please reach out to **ax-dev@google.com**!\n\nAX, short for Agent eXecutor, is a distributed agent runtime. It provides a\nruntime that coordinates agentic loops, manages executions with event logging,\nand communicates with both local and remote actors.\nAX is designed for reliability, with native support for recovery\nand execution resumption, even in complex distributed setups.\n\n## Features\n\n- **Distributed Runtime**: Controller, skills, tools, and agents can execute in isolation\n- **Resumption**: Automatic recovery from failures or interruptions\n- **Skills, Tools, Agents**: Support for skill, tool, and agent selection and execution\n- **Auditing & Policy**: All user and agentic calls are coordinated by a common controller, easy to control and audit the overall execution and skill\u002Ftool\u002Fagent calls\n- **Portability**: Runs anywhere, scales to small and large deployments\n- **Customizability**: Agnostic of harness and model\n\nBuilt-in consistency and resumability features:\n- **Single-Writer Architecture**: Single controller ensures consistent state management\n- **Event Log**: Durable execution state with automatic recovery\n- **Advanced Resumption**: Support for compute-layer actor resumption on compatible platforms\n\n## Demo\n\n[![Demo](https:\u002F\u002Fi.imgur.com\u002FADiU1OP.png)](https:\u002F\u002Fwww.youtube.com\u002Fwatch?v=L5Iw1IrZ6Nc)\n\nWatch our demo to see AX works when deployed on [Agent Substrate](https:\u002F\u002Fgithub.com\u002Fagent-substrate\u002Fsubstrate).\n\n## Overview\n\n```mermaid\n%%{init: {\"flowchart\": {\"diagramPadding\": 80}}}%%\ngraph LR\n    Client\n    Router[\"Router\"]\n    Controller[\"AX Controller\u003Cbr\u002F>(executor, event log, registry)\"]\n    RemoteAgent[\"Agent\u003Cbr\u002F>(isolated actor)\"]\n    Tool[\"Tool\u003Cbr\u002F>(MCP server)\"]\n    Env[\"Environment with\u003Cbr\u002F>skills, built-in tools\u003Cbr\u002F>(isolated actor)\"]\n\n    Client -->|resumable stream| Router\n    Router --> Controller\n    Controller \u003C-->|resumable stream| RemoteAgent\n    Controller --> Env\n    Controller --> Tool\n```\n\nAs agents evolve from simple assistants to autonomous long running workers,\ndevelopers need a robust runtime to manage state, ensure reliability,\nand audit execution. As we are moving away from monolithic agents towards\ndistributed harnesses where tools, skills and agents are deployed as\nisolated actors, a distributed runtime with dynamically spawned isolated\nworkers becomes a necessity. AX provides the foundational layer to fill these gaps.\n\nWhile compute-agnostic, AX is aiming to provide the best\nexperience on Kubernetes.\n\nWe expect every sophisticated agentic application will need the capabilities provided by AX.\nWe are building this layer as a widely available foundation,\nenabling developers to focus on building their applications rather than infrastructure.\nWe decided to build this project in public to validate every design decision before\na stable release is cut. We highly encourage you to give us feedback.\n\n## Installation\n\nInstall the ax CLI directly from the repository:\n\n```bash\ngo install github.com\u002Fgoogle\u002Fax\u002Fcmd\u002Fax@latest\n```\n\n### Verify Installation\n\nCheck that ax is installed correctly:\n\n```bash\nax --help\n```\n\nYou should see the ax CLI usage information.\n\n### Kubernetes\n\nAX is natively supported on\n[Agent Substrate](https:\u002F\u002Fgithub.com\u002Fagent-substrate\u002Fsubstrate)\non Kubernetes and it's the recommended deployment option for production\nuse. For more details on setup and configuration, see the\n[deployment guide](.\u002Fmanifests\u002FREADME.md).\n\nRead more about [this new layer](https:\u002F\u002Fcloud.google.com\u002Fblog\u002Fproducts\u002Fcontainers-kubernetes\u002Fbringing-you-agent-sandbox-on-gke-and-agent-substrate)\nthat provides higher density to agentic workloads on Kubernetes.\n\n## Quick Start\n\n### 1. Execute\n\nThe CLI provides an easy way to execute by using the\nagents and built-in tools already linked into the AX binary.\n\n```bash\n# Using default ax.yaml\nax exec --input \"Can you list me this directory?\"\n\n# Using exec with an AX server\nax exec --input \"Can you list me this directory?\" --server localhost:8494\n```\n\nConversations can be continued any time:\n\n```bash\nax exec \\\n  --conversation d85a4b4e-c53b-4c84-b879-f10d905bce40 \\\n  --input \"Show me the contents of README.md\"\n```\n\nIf the client gets disconnected, pass the last sequence it saw to\nreplay the events it missed. This catches the client up; it does not\nrewind the conversation. To branch from a checkpoint, use `ax fork`\ninstead.\n\nIn this example, we catch up a client from sequence number 12:\n\n```bash\nax exec \\\n  --conversation d85a4b4e-c53b-4c84-b879-f10d905bce40 \\\n  --last-seq 12 \\\n  --resume\n```\n\nInstead of running the default planning step, you can start executing\nfrom any registered agent:\n\n```bash\nax exec \\\n  --agent coding \\\n  --input \"Can you write me a simple HTTP server in Python?\"\n```\n\nIf anything goes wrong during the execution of an agent,\nyou can resume an incomplete execution in a conversation:\n```bash\nax exec \\\n  --conversation edf98ef5-4bb1-4a9e-a091-3a77e03727e6 \\\n  --agent \"coding\" \\\n  --resume\n```\n\n### 2. Execute with Custom Agents\n\nMost developers want to build their own agents. AX allows running custom agents as remote\nor sandbox agents. See [Custom Agents](#custom-agents) for a full list of supported agents.\n\nThis example demonstrates how the AX server executes remote agents\nthrough the `AgentService.Connect` RPC.\n\n**Terminal 1** - Start the remote agent server:\n```bash\ngo run examples\u002Fremote_agent\u002Fmain.go\n```\nThe remote agent runs as a gRPC server implementing `AgentService` on port `:50051`.\n\n**Terminal 2** - Start the AX controller server:\n```bash\n# Ensure the agent is registered as a remote agent in ax.yaml.\ncat ax.yaml\n# ...\nregistry:\n  remote_agents:\n    - id: \"lowercase\"\n      name: \"Lowercase Agent\"\n      description: \"Converts text to lowercase.\"\n      address: \"localhost:50051\"\n\nax serve\n```\nThe server exposes the service on port `:8494` by default.\n\n**Terminal 3** - Register the remote agent and execute:\n```bash\nax exec \\\n    --server localhost:8494 \\\n    --input \"HELLO, CAN YOU LOWERCASE WHAT I JUST SAID?\"\n```\n\n## Usage\n\nThe `ax` command provides several subcommands:\n\n### Execute\n\n```bash\nax exec \\\n    [--input \u003Ctext>] \\\n    [--conversation \u003Cid>] \\\n    [--agent \u003Cid>] \\\n    [--server \u003Caddress>] \\\n    [--config \u003Cfile>] \\\n    [--resume] \\\n    [--last-seq \u003Cnumber>]\n```\n\nExecutes a new agentic execution or automatically resumes an existing one. If the conversation ID already exists, the execution will be resumed from its last state.\n\nOptions:\n- `--input`: Input message to send to agents (optional if `--resume` is set, otherwise required)\n- `--conversation`: Conversation ID (optional, generates UUID if not provided, or resumes if exists)\n- `--agent`: Agent ID to use (optional, defaults to planner)\n- `--server`: gRPC controller server address (optional. If not provided, runs with a local built-in AX server)\n- `--config`: Path to YAML configuration file (only used with a local built-in AX server, default: \"ax.yaml\")\n- `--resume`: Resume a conversation without inputs (optional, mutually exclusive with `--input`)\n- `--last-seq`: Last sequence number seen by the client to resume from (optional). The server replays any later events so the client can catch up after a disconnect.\n\n**Examples:**\n\n```bash\n# Execute a new execution\nax exec --input \"Hello agents!\"\n\n# Resume an existing execution with new input\nax exec --conversation a53d4db3-1165-4925-87da-be6c72bbdeb1 --input \"Ok, now let's do something else...\"\n\n# Execute using server mode\nax exec --server localhost:8494 --input \"Hello agents!\"\n\n# Execute using a custom agent\nax exec --agent coding --input \"Hello coding agent, write me a cool Go program!\"\n```\n\n### Serve\n\n```bash\nax serve [--config \u003Cpath>]\n```\n\nStarts the controller as a gRPC server using a YAML configuration file.\n\nOptions:\n- `--config`: Path to YAML configuration file (default: \"ax.yaml\")\n\nExample configuration file (`ax.yaml`):\n```yaml\nserver:\n  address: \":8494\"\n\neventlog:\n  sqlite:\n    filename: \"eventlog\u002Flog.sqlite\"\n\nplanner:\n  gemini:\n    model: \"gemini-3.5-flash\"\n    timeout: \"60s\"\n    skills_dir: \".\u002Fexamples\u002Fskills\"\n\nregistry:\n  remote_agents:\n    - id: \"medical-deep-researcher\"\n      name: \"Medical Deep Researcher\"\n      description: \"Performs deep medical research using various resources like pubmed and clinicaltrials.gov\"\n      address: \"localhost:50051\"\n```\n\nExample:\n```bash\n# Start server with default config (ax.yaml)\nax serve\n\n# Start server with custom config\nax serve --config my-config.yaml\n```\n\n### Fork\n\nFork an existing agentic event log from a specific checkpoint (or the latest state)\ninto a new event log.\n\n```bash\nax fork \\\n    --src-conversation \u003Cid> \\\n    --dest-conversation \u003Cid> \\\n    [--src-seq \u003Cnumber>] \\\n    [--server \u003Caddress>]\n```\n\nOptions:\n- `--src-conversation`: Source conversation ID to fork from (required)\n- `--dest-conversation`: Destination conversation ID for the new event log (required)\n- `--src-seq`: Sequence number to fork from (optional, defaults to latest). Must be a sequence that exists in the source conversation.\n- `--server`: gRPC controller server address (default: \"localhost:8494\")\n\n**Example:**\n\n```bash\n# Fork from the latest state into a new conversation\nax fork --src-conversation 38460323-9a78-41cb-8991-022b0ff2c19c \\\n        --dest-conversation e5e26e38-53a2-4f22-b1cb-ae867357df83\n\n# Fork from a specific checkpoint\nax fork --src-conversation 38460323-9a78-41cb-8991-022b0ff2c19c \\\n        --dest-conversation e5e26e38-53a2-4f22-b1cb-ae867357df83 \\\n        --src-seq 12\n```\n\n### Trace\n\nVisualize the trace of an agentic execution in a Web UI, directly fetching from the event log.\n\n```bash\nax trace --conversation \u003Cid> [--addr \u003Caddress>] [--config \u003Cfile>]\n```\n\nThis will parse the execution logs and spin up a local web server, automatically opening it in your browser.\n\nOptions:\n- `--addr`: Server address to listen on (optional, defaults to \"localhost:8080\")\n- `--config`: Path to YAML configuration file (optional, defaults to \"ax.yaml\")\n\n**Examples:**\n\n```bash\n# Trace on default server localhost:8080\nax trace --conversation 1a6e0b29-87c2-4af0-81ac-0c73bf8fa293\n\n# Trace on a custom server address and port\nax trace --conversation 1a6e0b29-87c2-4af0-81ac-0c73bf8fa293 --addr 0.0.0.0:9090\n```\n\n## Gemini Agent\n\nAX includes a built-in Gemini agent that can be used to generate text based on a given prompt. The agent is registered as `gemini` and can be triggered as a standalone agent or used from custom agent implementations.\n\n```bash\nax exec --agent gemini \\\n  --input \"Hello, how are you?\"\n```\n\n### Authentication\n\nThe Gemini agent supports authentication using either Google AI Studio or Vertex AI:\n\n```bash\n# AI Studio API key based authentication.\nexport GEMINI_API_KEY=\"your-api-key\"\n\n# Vertex AI based authentication, ensure application\n# default credentials are set up, gcloud auth application-default login.\nexport GOOGLE_CLOUD_PROJECT=\"your-project-id\"\nexport GOOGLE_CLOUD_LOCATION=\"us-central1\"\nexport GOOGLE_GENAI_USE_VERTEXAI=True\n```\n\n## Extensions\n\n### Skills\n\nAX includes built-in support for Agent Skills. See [Skills](examples\u002Fskills) for more.\n\n### Bash Tool\n\nThe built-in planner is equipped with a `bash` tool that enables\nit to execute general-purpose shell commands. The tool automatically\nadapts to the user's operating system.\n\nFor safety and control, any execution initiated by the bash tool\nrequires explicit user approval via a confirmation flow before running.\n\n### Custom Agents\n\nAX supports multiple ways to bring your own agents into the runtime.\n\n#### Remote agents\n\nRemote agents run outside the AX controller and are\ninvoked over a protocol boundary.\n\n- [Remote Agent](examples\u002Fremote_agent) implements AX's native `AgentService` directly.\n- [ADK Agent (Python)](examples\u002Fadk_agent) runs a Google ADK agent as a remote agent.\n- [A2A Agent](examples\u002Fa2a_agent) connects agents that speak the [A2A protocol](https:\u002F\u002Fgithub.com\u002Fa2aproject\u002FA2A) through AX's A2A bridge.\n- [Colab Agents (Experimental)](examples\u002Fcolab_agent) runs Python scripts or notebooks in a remote Google Colab session.\n\nPlease note that AX is actively developing its resumable streaming and agent communication protocols; these interfaces will change before a stable release.\n\nIf you are implementing an AX-native remote agent, see `AgentService` in `proto\u002Fax.proto`.\n\n## What AX is NOT?\n* A managed service. AX is self-hosted and not a managed service.\n  We aim to make it easy for users to deploy and operate it on\n  their Kubernetes clusters.\n* An agentic framework. AX is agnostic of the framework used to build agents.\n  We are working with other framework authors (e.g., [ADK](examples\u002Fadk_agent))\n  to provide easy integration with them.\n* A specific harness like a specific coding agent, e.g. Antigravity.\n  AX provides the serving layer around harnesses and is agnostic of the\n  harness implementation. Soon, we will allow users to bring their own\n  harnesses.\n* A model specific controller. AX is agnostic of the models used.\n\n## Roadmap\n\nBelow is an overview of our upcoming features and planned changes:\n\n1. Antigravity as the built-in harness\n1. Support for BYOH (Bring Your Own Harness)\n1. Enabling suspension\u002Fresumption of subagents\n1. Support for tool call approvals in subagents\n1. Improvements to resumption protocols\n\n## Contributing\n\nPlease refer to the [CONTRIBUTING.md](CONTRIBUTING.md) guide for instructions\non how to contribute to this project.\n\nWe are currently undergoing a significant architectural redesign, and external contributions are temporarily paused.\nHowever, in the meantime, we warmly encourage you to file bugs and\nsend feature requests.\n\n## Acknowledgements\n\nWe thank Google DeepMind for their earlier work in distributed harnesses which\nheavily influenced AX.\nWe thank the Google Kubernetes Engine team for their deep contributions\nregarding isolation, resumption and job scheduling.\n\n## License\n\nApache 2.0\n","AX是Google开源的一个分布式代理运行时，旨在协调代理循环、管理执行过程中的事件日志，并与本地及远程参与者通信。其核心功能包括支持分布式运行环境下的组件隔离执行、自动恢复中断或故障的能力、以及对技能、工具和代理选择与执行的支持。此外，AX还具备审计和策略控制特性，确保所有用户和代理调用的可追踪性。它适用于需要高可靠性和可恢复性的复杂分布式系统场景，如长时间运行的自主工作代理。AX的设计考虑了从简单助手到复杂自主工作者的演变需求，提供了一个灵活且可扩展的基础架构来满足这些要求。",2,"2026-06-11 04:08:43","high_star"]