From c102d4ba1512b72a729cdff926007559de151be2 Mon Sep 17 00:00:00 2001 From: Yiorgis Gozadinos Date: Thu, 9 Oct 2025 14:49:45 +0300 Subject: [PATCH] Document a2a --- README.md | 15 +++++++++ docs/a2a.md | 83 ++++++++++++++++++++++++++++++++++++++++++++++++++ docs/index.md | 4 ++- docs/server.md | 16 +++++++++- mkdocs.yml | 1 + 5 files changed, 117 insertions(+), 2 deletions(-) create mode 100644 docs/a2a.md diff --git a/README.md b/README.md index c97c15c7..098e53d0 100644 --- a/README.md +++ b/README.md @@ -18,6 +18,7 @@ Retrieval-Augmented Generation (RAG) library built on LanceDB. - **File monitoring**: Auto-index files when run as server - **40+ file formats**: PDF, DOCX, HTML, Markdown, code files, URLs - **MCP server**: Expose as tools for AI assistants +- **A2A agent**: Conversational agent with context and multi-turn dialogue - **CLI & Python API**: Use from command line or Python ## Quick Start @@ -143,6 +144,20 @@ haiku-rag serve --stdio Provides tools for document management and search directly in your AI assistant. +## A2A Agent + +Run as a conversational agent with the Agent-to-Agent protocol: + +```bash +haiku-rag serve --a2a +``` + +Provides a conversational interface with: +- Multi-turn dialogue with context +- Intelligent multi-search for complex questions +- Source citations with titles and URIs +- Full document retrieval on request + ## Documentation Full documentation at: https://ggozad.github.io/haiku.rag/ diff --git a/docs/a2a.md b/docs/a2a.md new file mode 100644 index 00000000..a90f2c1e --- /dev/null +++ b/docs/a2a.md @@ -0,0 +1,83 @@ +# Agent-to-Agent (A2A) Protocol + +The A2A server exposes `haiku.rag` as a conversational agent using the Agent-to-Agent protocol. Unlike the MCP server which provides stateless tools, the A2A agent maintains conversation history and context across multiple turns. + +## Features + +- **Conversational Context**: Maintains full conversation history including tool calls and results +- **Multi-turn Dialogue**: Supports follow-up questions with pronoun resolution ("he", "it", "that document") +- **Intelligent Search**: Performs single or multiple searches depending on question complexity +- **Source Citations**: Always includes sources with both titles and URIs +- **Full Document Retrieval**: Can fetch complete documents on request +- **Document Discovery**: Lists available documents to help users explore the knowledge base + +## Starting A2A Server + +```bash +haiku-rag serve --a2a +``` + +Server options: +- `--a2a-host` - Host to bind to (default: 127.0.0.1) +- `--a2a-port` - Port to bind to (default: 8000) + +Example: +```bash +haiku-rag serve --a2a --a2a-host 0.0.0.0 --a2a-port 8080 +``` + +## Requirements + +A2A support requires the `a2a` extra: + +```bash +uv pip install 'haiku.rag[a2a]' +``` + +## Python Usage + +```python +from pathlib import Path +from haiku.rag.a2a import create_a2a_app +import uvicorn + +# Create A2A app +app = create_a2a_app(Path("database.lancedb")) + +# Run with uvicorn +uvicorn.run(app, host="127.0.0.1", port=8000) +``` + +This installs the `fasta2a` package and its dependencies. + +## Architecture + +The A2A agent uses: + +- **FastA2A**: Python framework implementing the A2A protocol +- **Pydantic AI**: Agent framework with tool support +- **In-Memory Storage**: Context and message history storage (persists during server lifetime) +- **Conversation State**: Full pydantic-ai message history serialized in A2A context + +### Message History + +The agent stores the complete conversation state including: + +- User prompts +- Agent responses +- Tool calls and their arguments +- Tool return values + +This enables the agent to: + +- Reference previous searches +- Understand pronouns and context +- Maintain coherent multi-turn conversations + +### Context Management + +Each conversation is identified by a `context_id`. All messages within the same context share conversation history. This allows the agent to: + +- Remember what was discussed +- Track which documents were already found +- Provide contextual follow-up answers diff --git a/docs/index.md b/docs/index.md index 648eb076..f3bc543d 100644 --- a/docs/index.md +++ b/docs/index.md @@ -10,10 +10,11 @@ - **Support for various embedding providers**: Ollama, VoyageAI, OpenAI or add your own - **Native Hybrid Search**: Vector search combined with full-text search using native LanceDB RRF reranking - **Reranking**: Optional result reranking with MixedBread AI or Cohere -- **Question Answering**: Built-in QA agents using Ollama, OpenAI, or Anthropic. +- **Question Answering**: Built-in QA agents using Ollama, OpenAI, or Anthropic - **File monitoring**: Automatically index files when run as a server - **Extended file format support**: Parse 40+ file formats including PDF, DOCX, HTML, Markdown, code files and more. Or add a URL! - **MCP server**: Exposes functionality as MCP tools +- **A2A agent**: Conversational agent with context and multi-turn dialogue support - **CLI commands**: Access all functionality from your terminal - Add sources from text, files, or URLs, optionally with a human‑readable title - **Python client**: Call `haiku.rag` from your own python applications @@ -57,6 +58,7 @@ haiku-rag migrate old_database.sqlite # Migrate from SQLite - [CLI](cli.md) - Command line interface usage - [Server](server.md) - File monitoring and server mode - [MCP](mcp.md) - Model Context Protocol integration +- [A2A](a2a.md) - Agent-to-Agent conversational protocol - [Python](python.md) - Python API reference - [Agents](agents.md) - QA agent and multi-agent research diff --git a/docs/server.md b/docs/server.md index 15f862b1..c1e7d7be 100644 --- a/docs/server.md +++ b/docs/server.md @@ -1,9 +1,11 @@ # Server Mode -The server provides automatic file monitoring and MCP functionality. +The server provides automatic file monitoring, MCP functionality, and A2A agent support. ## Starting the Server +### MCP Server (Default) + ```bash haiku-rag serve ``` @@ -12,6 +14,18 @@ Transport options: - Default - Streamable HTTP transport - `--stdio` - Standard input/output transport +### A2A Server + +```bash +haiku-rag serve --a2a +``` + +Options: +- `--a2a-host` - Host to bind to (default: 127.0.0.1) +- `--a2a-port` - Port to bind to (default: 8000) + +See [A2A documentation](a2a.md) for details on the conversational agent. + ## File Monitoring Set `MONITOR_DIRECTORIES` environment variable to enable automatic file monitoring: diff --git a/mkdocs.yml b/mkdocs.yml index 2edd9719..34b54627 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -64,6 +64,7 @@ nav: - Agents: agents.md - Python: python.md - MCP: mcp.md + - A2A: a2a.md - Benchmarks: benchmarks.md markdown_extensions: - admonition