ADK Middleware Integration

.gitignore

@@ -1,2 +1,3 @@
+**/.claude/settings.local.json
 .vscode/
 .idea/

typescript-sdk/.gitignore

@@ -44,4 +44,5 @@ packages/proto/src/generated
 **/**/.langgraph_api
 
 # Python
+venv
 __pycache__/

typescript-sdk/apps/dojo/e2e2/tests/adk-middleware-agentic-chat.spec.ts

@@ -0,0 +1,23 @@
+import { test, expect } from '@playwright/test';
+
+test('responds to user message', async ({ page }) => {
+  await page.goto('http://localhost:9999/adk-middleware/feature/agentic_chat');
+
+  // 1. Wait for the page to be fully ready by ensuring the initial message is visible.
+  await expect(page.getByText("Hi, I'm an agent. Want to chat?")).toBeVisible({ timeout: 10000 });
+
+  // 2. Interact with the page to send the message.
+  const textarea = page.getByPlaceholder('Type a message...');
+  await textarea.fill('How many sides are in a square? Please answer in one word. Do not use any punctuation, just the number in word form.');
+  await page.keyboard.press('Enter');
+
+  // 3. Assert the final state with a generous timeout.
+  //    This is the most important part. We target the *second* assistant message
+  //    and wait for it to contain the text "Four". Playwright handles all the waiting.
+  const finalResponse = page.locator('.copilotKitMessage.copilotKitAssistantMessage').nth(1);
+  await expect(finalResponse).toContainText(/four/i, { timeout: 15000 });
+
+  // 4. (Optional) For added certainty, verify the total message count.
+  //    This confirms there are exactly 3 messages: greeting, user query, and agent response.
+  await expect(page.locator('.copilotKitMessage')).toHaveCount(3);
+});

typescript-sdk/apps/dojo/scripts/generate-content-json.ts

@@ -204,6 +204,12 @@ const agentFilesMapper: Record<string, (agentKeys: string[]) => Record<string, s
       ...acc,
       [agentId]: [path.join(__dirname, integrationsFolderPath, `/crewai/python/ag_ui_crewai/examples/${agentId}.py`)]
     }), {})
+  },
+  'adk-middleware': (agentKeys: string[]) => {
+    return agentKeys.reduce((acc, agentId) => ({
+      ...acc,
+      [agentId]: [path.join(__dirname, integrationsFolderPath, `/adk-middleware/examples/fastapi_server.py`)]
+    }), {})
   }
 }
 

typescript-sdk/apps/dojo/src/agents.ts

@@ -59,6 +59,18 @@ export const agentsIntegrations: AgentIntegrationConfig[] = [
       };
     },
   },
+  {
+    id: "adk-middleware",
+    agents: async () => {
+      return {
+        agentic_chat: new ServerStarterAgent({ url: `${envVars.adkMiddlewareUrl}/chat` }),
+        tool_based_generative_ui: new ServerStarterAgent({ url: `${envVars.adkMiddlewareUrl}/adk-tool-based-generative-ui` }),
+        human_in_the_loop: new ServerStarterAgent({ url: `${envVars.adkMiddlewareUrl}/adk-human-in-loop-agent` }),
+        shared_state: new ServerStarterAgent({ url: `${envVars.adkMiddlewareUrl}/adk-shared-state-agent` }),
+        predictive_state_updates: new ServerStarterAgent({ url: `${envVars.adkMiddlewareUrl}/adk-predictive-state-agent` }),
+      };
+    },
+  },
   {
     id: "server-starter-all-features",
     agents: async () => {

typescript-sdk/apps/dojo/src/env.ts

@@ -9,6 +9,7 @@ type envVars = {
   llamaIndexUrl: string;
   crewAiUrl: string;
   pydanticAIUrl: string;
+  adkMiddlewareUrl: string;
   customDomainTitle: Record<string, string>;
 }
 
@@ -32,6 +33,7 @@ export default function getEnvVars(): envVars {
     llamaIndexUrl: process.env.LLAMA_INDEX_URL || 'http://localhost:9000',
     crewAiUrl: process.env.CREW_AI_URL || 'http://localhost:9002',
     pydanticAIUrl: process.env.PYDANTIC_AI_URL || 'http://localhost:9000',
+    adkMiddlewareUrl: process.env.ADK_MIDDLEWARE_URL || 'http://localhost:8000',
     customDomainTitle: customDomainTitle,
   }
 }

typescript-sdk/apps/dojo/src/menu.ts

@@ -11,6 +11,11 @@ export const menuIntegrations: MenuIntegrationConfig[] = [
     name: "Server Starter",
     features: ["agentic_chat"],
   },
+  {
+    id: "adk-middleware",
+    name: "ADK Middleware",
+    features: ["agentic_chat","tool_based_generative_ui","human_in_the_loop","shared_state","predictive_state_updates"],
+  },
   {
     id: "server-starter-all-features",
     name: "Server Starter (All Features)",

typescript-sdk/integrations/adk-middleware/.gitignore

@@ -0,0 +1,86 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual Environment
+venv/
+env/
+ENV/
+env.bak/
+venv.bak/
+test_env/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.project
+.pydevproject
+
+# Testing
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Development scripts and temp files
+set_pythonpath.sh
+simple_test_server.py
+
+# External project directories
+
+# Local documentation
+CLAUDE.md

typescript-sdk/integrations/adk-middleware/ARCHITECTURE.md

@@ -0,0 +1,128 @@
+# ADK Middleware Architecture
+
+This document describes the architecture and design of the ADK Middleware that bridges Google ADK agents with the AG-UI Protocol.
+
+## High-Level Architecture
+
+```
+AG-UI Protocol          ADK Middleware           Google ADK
+     │                        │                       │
+RunAgentInput ──────> ADKAgent.run() ──────> Runner.run_async()
+     │                        │                       │
+     │                 EventTranslator                │
+     │                        │                       │
+BaseEvent[] <──────── translate events <──────── Event[]
+```
+
+## Core Components
+
+### ADKAgent (`adk_agent.py`)
+The main orchestrator that:
+- Manages agent lifecycle and session state
+- Handles the bridge between AG-UI Protocol and ADK
+- Coordinates tool execution through proxy tools
+- Implements direct agent embedding pattern
+
+### EventTranslator (`event_translator.py`)
+Converts between event formats:
+- ADK events → AG-UI protocol events (16 standard event types)
+- Maintains proper message boundaries
+- Handles streaming text content
+- Per-session instances for thread safety
+
+### SessionManager (`session_manager.py`)
+Singleton pattern for centralized session control:
+- Automatic session cleanup with configurable timeouts
+- Session isolation per user
+- Memory service integration for session persistence
+- Resource management and limits
+
+### ExecutionState (`execution_state.py`)
+Tracks background ADK executions:
+- Manages asyncio tasks running ADK agents
+- Event queue for streaming results
+- Execution timing and completion tracking
+- Tool call state management
+
+### ClientProxyTool (`client_proxy_tool.py`)
+Individual tool proxy implementation:
+- Wraps AG-UI tools for ADK compatibility
+- Emits tool events to client
+- Currently all tools are long-running
+- Integrates with ADK's tool system
+
+### ClientProxyToolset (`client_proxy_toolset.py`)
+Manages collections of proxy tools:
+- Dynamic toolset creation per request
+- Fresh tool instances for each execution
+- Combines client and backend tools
+
+## Event Flow
+
+1. **Client Request**: AG-UI Protocol `RunAgentInput` received
+2. **Session Resolution**: SessionManager finds or creates session
+3. **Agent Execution**: ADK Runner executes agent with context
+4. **Tool Handling**: ClientProxyTools emit events for client-side execution
+5. **Event Translation**: ADK events converted to AG-UI events
+6. **Streaming Response**: Events streamed back via SSE or other transport
+
+## Key Design Patterns
+
+### Direct Agent Embedding
+```python
+# Agents are directly embedded in ADKAgent instances
+agent = ADKAgent(
+    adk_agent=my_adk_agent,  # Direct reference
+    app_name="my_app",
+    user_id="user123"
+)
+```
+
+### Service Dependency Injection
+The middleware uses dependency injection for ADK services:
+- Session service (default: InMemorySessionService)
+- Memory service (optional, enables session persistence)
+- Artifact service (default: InMemoryArtifactService)
+- Credential service (default: InMemoryCredentialService)
+
+### Tool Proxy Pattern
+All client-supplied tools are wrapped as long-running ADK tools:
+- Emit events for client-side execution
+- Can be combined with backend tools
+- Unified tool handling interface
+
+### Session Lifecycle
+1. Session created on first request
+2. Maintained across multiple runs
+3. Automatic cleanup after timeout
+4. Optional persistence to memory service
+
+## Thread Safety
+
+- Per-session EventTranslator instances
+- Singleton SessionManager with proper locking
+- Isolated execution states per thread
+- Thread-safe event queues
+
+## Error Handling
+
+- RunErrorEvent for various failure scenarios
+- Proper async exception handling
+- Resource cleanup on errors
+- Timeout management at multiple levels
+
+## Performance Considerations
+
+- Async/await throughout for non-blocking operations
+- Event streaming for real-time responses
+- Configurable concurrent execution limits
+- Automatic stale execution cleanup
+- Efficient event queue management
+
+## Future Enhancements
+
+- Additional tool execution modes
+- Enhanced state synchronization
+- More sophisticated error recovery
+- Performance optimizations
+- Extended protocol support