Install and Integrate A2A Protocol (@a2a-js/sdk)

A2A_CONFIGURATION.md

@@ -0,0 +1,91 @@
+# Agent-to-Agent (A2A) Protocol Configuration & Usage Guide
+
+This repository integrates the official **Agent-to-Agent (A2A) Protocol** ([a2a-protocol.org](https://a2a-protocol.org)) using [`@a2a-js/sdk`](https://github.com/a2aproject/a2a-js). QCX-Terra can act both as an **A2A Client** (invoking specialized remote agents on other systems) and as an **A2A Server** (allowing external agentic systems to discover and send tasks to QCX-Terra).
+
+---
+
+## 1. Environment Configuration
+
+### Remote Agents (`A2A_REMOTE_AGENTS`)
+
+Configure remote A2A agents that QCX-Terra can communicate with using the `A2A_REMOTE_AGENTS` environment variable in `.env.local` or your runtime environment:
+
+```env
+A2A_REMOTE_AGENTS='[
+  {
+    "name": "weather-agent",
+    "url": "https://weather.example.com",
+    "apiKey": "sk_live_12345"
+  },
+  {
+    "name": "satellite-imagery-agent",
+    "url": "https://sat.example.com"
+  }
+]'
+```
+
+- **`name`**: Friendly identifier for the remote agent (used by internal agents for routing).
+- **`url`**: The base HTTP/HTTPS URL of the remote agent serving `/.well-known/agent-card.json`.
+- **`apiKey`** *(optional)*: Bearer token or authorization token injected into the `Authorization` request header.
+
+---
+
+## 2. A2A Client Capabilities
+
+QCX-Terra's multi-agent system (`lib/agents/researcher.tsx`) includes the `a2aQueryTool` tool.
+
+When a user asks QCX-Terra to consult or delegate sub-tasks to external agents (e.g., *"Ask the weather agent for the atmospheric forecast in Oregon"* or *"Delegate satellite task to https://sat.example.com"*), the agent automatically uses `a2aQueryTool` to:
+
+1. Resolve the remote agent's URL and credentials from `A2A_REMOTE_AGENTS` or prompt argument.
+2. Fetch the remote agent card via `@a2a-js/sdk` `ClientFactory`.
+3. Negotiate transport (JSON-RPC or HTTP REST).
+4. Stream or send the request message and return the synthesized result to the user interface.
+
+---
+
+## 3. A2A Server Endpoints
+
+QCX-Terra exposes compliant A2A v1.0 server endpoints:
+
+### Agent Card Discovery
+- **Endpoint**: `GET /.well-known/agent-card.json`
+- **Description**: Returns QCX-Terra's agent card, detailing supported interfaces (`JSON-RPC`, `HTTP+REST`), streaming capabilities, and available skills (`geospatial-analysis`, `satellite-embeddings`, `planet-computer`).
+
+### Message & Task Execution Endpoint
+- **Endpoint**: `POST /api/a2a`
+- **Description**: Handles inbound A2A v1.0 JSON-RPC requests (`SendMessage`, `SendStreamingMessage`, `GetTask`, `CancelTask`, etc.).
+
+#### Example Inbound JSON-RPC Request:
+```bash
+curl -X POST http://localhost:3000/api/a2a \
+  -H "Content-Type: application/json" \
+  -d '{
+    "jsonrpc": "2.0",
+    "id": 1,
+    "method": "SendMessage",
+    "params": {
+      "message": {
+        "messageId": "msg-001",
+        "role": "ROLE_USER",
+        "parts": [
+          {
+            "content": {
+              "$case": "text",
+              "value": "Query latest geospatial analysis for target region."
+            }
+          }
+        ]
+      }
+    }
+  }'
+```
+
+---
+
+## 4. Testing & Verification
+
+Run the A2A integration test suite using Bun:
+
+```bash
+bun test tests-unit/a2a.test.ts
+```

app/.well-known/agent-card.json/route.ts

@@ -0,0 +1,65 @@
+import { NextResponse } from 'next/server'
+
+export async function GET(request: Request) {
+  const host = request.headers.get('host') || 'localhost:3000'
+  const protocol = request.headers.get('x-forwarded-proto') || 'http'
+  const baseUrl = `${protocol}://${host}`
+
+  const agentCard = {
+    name: 'QCX-Terra Agent',
+    description:
+      'Environment-aware planetary computer platform offering geospatial analysis, remote sensing satellite imagery processing, and multi-agent exploration.',
+    supportedInterfaces: [
+      {
+        protocolBinding: 'JSON-RPC',
+        protocolVersion: '1.0',
+        url: `${baseUrl}/api/a2a`
+      },
+      {
+        protocolBinding: 'HTTP+JSON/REST',
+        protocolVersion: '1.0',
+        url: `${baseUrl}/api/a2a`
+      }
+    ],
+    capabilities: {
+      streaming: true,
+      pushNotifications: false
+    },
+    skills: [
+      {
+        id: 'geospatial-analysis',
+        name: 'Geospatial Analysis & Mapping',
+        description: 'Perform spatial queries, location search, routing, and map feature analysis.'
+      },
+      {
+        id: 'satellite-embeddings',
+        name: 'Satellite Image Vector Search',
+        description: 'Natural language and vector similarity search over satellite and aerial imagery.'
+      },
+      {
+        id: 'planet-computer',
+        name: 'Planetary Computing & Forecasting',
+        description: 'Provide climate forecasting, planetary model exploration, and environmental insights.'
+      }
+    ]
+  }
+
+  return NextResponse.json(agentCard, {
+    headers: {
+      'Access-Control-Allow-Origin': '*',
+      'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
+      'Access-Control-Allow-Headers': 'Content-Type, Authorization, A2A-Version'
+    }
+  })
+}
+
+export async function OPTIONS() {
+  return new Response(null, {
+    status: 204,
+    headers: {
+      'Access-Control-Allow-Origin': '*',
+      'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
+      'Access-Control-Allow-Headers': 'Content-Type, Authorization, A2A-Version'
+    }
+  })
+}

app/api/a2a/route.ts

@@ -0,0 +1,177 @@
+import { NextResponse } from 'next/server'
+import {
+  DefaultRequestHandler,
+  JsonRpcTransportHandler,
+  InMemoryTaskStore,
+  AgentEvent,
+  RequestContext,
+  ExecutionEventBus,
+  ServerCallContext
+} from '@a2a-js/sdk/server'
+import { Role, TaskState } from '@a2a-js/sdk'
+
+const agentCard = {
+  name: 'QCX-Terra Agent',
+  description:
+    'Environment-aware planetary computer platform offering geospatial analysis, remote sensing satellite imagery processing, and multi-agent exploration.',
+  supportedInterfaces: [
+    {
+      protocolBinding: 'JSON-RPC',
+      protocolVersion: '1.0',
+      url: '/api/a2a',
+      tenant: ''
+    }
+  ],
+  provider: undefined,
+  version: '1.0.0',
+  capabilities: {
+    streaming: true,
+    pushNotifications: false,
+    extensions: []
+  },
+  securitySchemes: {},
+  securityRequirements: [],
+  defaultInputModes: ['text/plain'],
+  defaultOutputModes: ['text/plain'],
+  skills: [],
+  signatures: []
+}
+
+const taskStore = new InMemoryTaskStore()
+
+const agentExecutor = {
+  async execute(requestContext: RequestContext, eventBus: ExecutionEventBus) {
+    const userMessage = requestContext.userMessage
+    let textPart = ''
+    if (userMessage.parts) {
+      for (const p of userMessage.parts) {
+        if (p.content?.$case === 'text') {
+          textPart += p.content.value
+        }
+      }
+    }
+
+    eventBus.publish(
+      AgentEvent.task({
+        id: requestContext.taskId,
+        contextId: requestContext.contextId,
+        status: {
+          state: TaskState.TASK_STATE_WORKING,
+          message: undefined,
+          timestamp: undefined
+        },
+        artifacts: [],
+        history: [userMessage],
+        metadata: undefined
+      })
+    )
+
+    const responseText = `QCX-Terra Agent received your request: "${textPart}". Processed via A2A Protocol.`
+
+    eventBus.publish(
+      AgentEvent.message({
+        messageId: `msg-${Date.now()}`,
+        taskId: requestContext.taskId,
+        contextId: requestContext.contextId,
+        role: Role.ROLE_AGENT,
+        parts: [
+          {
+            content: {
+              $case: 'text',
+              value: responseText
+            },
+            metadata: undefined,
+            filename: '',
+            mediaType: 'text/plain'
+          }
+        ],
+        metadata: undefined,
+        extensions: [],
+        referenceTaskIds: []
+      })
+    )
+
+    eventBus.publish(
+      AgentEvent.statusUpdate({
+        taskId: requestContext.taskId,
+        contextId: requestContext.contextId,
+        status: {
+          state: TaskState.TASK_STATE_COMPLETED,
+          message: undefined,
+          timestamp: undefined
+        },
+        metadata: undefined
+      })
+    )
+  },
+  async cancelTask(_taskId: string, _eventBus: ExecutionEventBus) {}
+}
+
+const handler = new DefaultRequestHandler(agentCard, taskStore, agentExecutor)
+const jsonRpcHandler = new JsonRpcTransportHandler(handler)
+
+export async function POST(request: Request) {
+  try {
+    const body = await request.json()
+    const headers: Record<string, string> = {}
+    request.headers.forEach((value, key) => {
+      headers[key] = value
+    })
+
+    const rpcResult = await jsonRpcHandler.handle(
+      body,
+      new ServerCallContext({ state: new Map([['headers', headers]]) })
+    )
+
+    if (rpcResult && typeof (rpcResult as any)[Symbol.asyncIterator] === 'function') {
+      const encoder = new TextEncoder()
+      const stream = new ReadableStream({
+        async start(controller) {
+          for await (const chunk of rpcResult as AsyncGenerator<any>) {
+            controller.enqueue(encoder.encode(JSON.stringify(chunk) + '\n'))
+          }
+          controller.close()
+        }
+      })
+
+      return new Response(stream, {
+        headers: {
+          'Content-Type': 'application/x-ndjson',
+          'Access-Control-Allow-Origin': '*'
+        }
+      })
+    }
+
+    return NextResponse.json(rpcResult, {
+      headers: {
+        'Access-Control-Allow-Origin': '*',
+        'Access-Control-Allow-Methods': 'POST, OPTIONS',
+        'Access-Control-Allow-Headers': 'Content-Type, Authorization, A2A-Version'
+      }
+    })
+  } catch (error: any) {
+    console.error('A2A Server POST Handler error:', error)
+    return NextResponse.json(
+      {
+        jsonrpc: '2.0',
+        id: null,
+        error: {
+          code: -32603,
+          message: error?.message || 'Internal error'
+        }
+      },
+      { status: 500 }
+    )
+  }
+}
+
+export async function OPTIONS() {
+  return new Response(null, {
+    status: 204,
+    headers: {
+      'Access-Control-Allow-Origin': '*',
+      'Access-Control-Allow-Methods': 'POST, OPTIONS',
+      'Access-Control-Allow-Headers': 'Content-Type, Authorization, A2A-Version'
+    }
+  })
+}

components/chat-share.tsx

@@ -1,6 +1,6 @@
 'use client'
 
-import { useState, useTransition, useEffect } from 'react'
+import { useState, useTransition, useEffect, useCallback } from 'react'
 import { Button } from './ui/button'
 import { Share, UserPlus, Trash2 } from 'lucide-react'
 import {
@@ -27,7 +27,7 @@ export function ChatShare({ chatId, className }: ChatShareProps) {
   const [participants, setParticipants] = useState<Participant[]>([])
   const [isLoadingParticipants, setIsLoadingParticipants] = useState(false)
 
-  const fetchParticipants = async () => {
+  const fetchParticipants = useCallback(async () => {
     setIsLoadingParticipants(true)
     try {
       const res = await fetch(`/api/chats/${chatId}/participants`)
@@ -40,13 +40,13 @@ export function ChatShare({ chatId, className }: ChatShareProps) {
     } finally {
       setIsLoadingParticipants(false)
     }
-  }
+  }, [chatId])
 
   useEffect(() => {
     if (open) {
       fetchParticipants()
     }
-  }, [open, chatId])
+  }, [open, fetchParticipants])
 
   const handleAddCollaborator = async (e: React.FormEvent) => {
     e.preventDefault()

components/chat.tsx

@@ -91,7 +91,7 @@ export function Chat({ id }: ChatProps) {
       }, 300);
       return () => clearTimeout(timer);
     }
-  }, [aiState.messages.length, router, isStandalone, lastMessage?.type])
+  }, [aiState.messages.length, router, isStandalone, lastMessage?.type, lastMessage?.id])
 
   // Subscribe to real-time database changes for messages and collaborators
   useEffect(() => {