Skip to main content
Got an existing A2A agent? You can connect it to Agent Stack instantly using the Agent Stack A2A Proxy — a lightweight tool that bridges your agent and the Agent Stack. No need to modify your agent’s code — just run one command and your agent will appear live in the Agent Stack interface.

​
Quickstart

​
Prerequisites

  • A running A2A agent with a valid agent card at /.well-known/agent-card.json
  • Node.js installed (for npx)
  • Agent Stack running (default: http://127.0.0.1:8333)
  • The proxy installed (npx i-am-bee/agentstack-a2a-proxy)

​
Connect Your Agent

  1. Start your A2A agent and note its URL (e.g., http://localhost:8080)
  2. Run the proxy pointing to your agent: 
npx i-am-bee/agentstack-a2a-proxy start http://localhost:8080
That’s it! Your agent is now registered with Agent Stack and accessible through the interface.

​
How It Works

The proxy creates a bridge between your A2A agent and Agent Stack by:
  1. Intercepting agent card requests - Captures /.well-known/agent-card.json requests from any A2A client
  2. Adding Agent Details extension - Automatically injects the necessary AgentDetail extension data that enables the agent to work within the Agent Stack ecosystem
  3. Auto-registration - Automatically registers the modified agent with the Agent Stack, making it immediately available
The proxy supports agents using jsonrpc and http_json transport protocols.

​
Configuration Options

​
Custom Proxy Port

By default, the proxy runs on port 8000. To use a different port: 
npx i-am-bee/agentstack-a2a-proxy start http://localhost:8080 --port 4000

​
Custom Platform URL

If your Agent Stack is running on a different URL: 
npx i-am-bee/agentstack-a2a-proxy start http://localhost:8080 --platform-url http://localhost:9000

​
Disable Auto-Registration

To run the proxy without automatically registering with Agent Stack: 
npx i-am-bee/agentstack-a2a-proxy start http://localhost:8080 --auto-register false

​
Custom Agent Details

You can customize the agent details extension data by providing a JSON file: 
npx i-am-bee/agentstack-a2a-proxy start http://localhost:8080 --custom-data ./my-agent-details.json

​
Available Options

OptionAliasDescriptionDefault
--port-pPort to run the proxy server on8000
--auto-register-aEnable/disable auto-registration with Agent Stacktrue
--platform-url-PPlatform URL to register withhttp://127.0.0.1:8333
--custom-data-cPath to custom agent detail JSON file-

​
Deploying to Production

The proxy is great for local development and testing. To deploy your agent to production, you’ll need to integrate Agent Stack directly into your agent code:
  1. Install the Agent Stack SDK:
   pip install agentstack-sdk
  1. Import and create an Agent Stack Server instance and wrap your existing A2A agent:
   from agentstack_sdk import Server
   
   server = Server()
   
   # Wrap your existing A2A agent function with the decorator
   @server.agent(
       name="My Agent",
       # ... your existing A2A agent card configuration
   )
   async def my_agent(input, context):
       # Your existing agent logic
       pass
  1. Add the Agent Details extension to configure how your agent appears in the Agent Stack UI:
   from agentstack_sdk.a2a.extensions import AgentDetail, AgentDetailTool
   
   @server.agent(
       name="My Agent",
       detail=AgentDetail(
           interaction_mode="multi-turn",
           user_greeting="Welcome! I'm here to help.",
           tools=[
               AgentDetailTool(name="Search", description="Search the web")
           ],
           framework="Your Framework"
       )
   )
   async def my_agent(input, context):
       # Your existing agent logic
       pass
  1. Add a run function to start the server:
   import os
   
   def run():
       server.run(
           host=os.getenv("HOST", "127.0.0.1"),
           port=int(os.getenv("PORT", 8000))
       )
   
   if __name__ == "__main__":
       run()
  1. Containerize your agent as a Docker image with the Agent Stack SDK included
  2. Deploy it as a managed provider to your Agent Stack instance
The agentstack-starter template provides production-ready infrastructure including Dockerfile, GitHub Actions workflow for automated container builds, and Agent Stack deployment configurations—use it as your starting point.

​
Next Steps

  • Test your agent in the Agent Stack interface at http://127.0.0.1:8333
  • Explore extensions to add UI enhancements and service integrations
  • Customize agent details to improve how your agent appears in the interface
  • Ready to deploy? Check out Deploying Agents when you want to publish your agent