From 3c78b717b01f49c40186979efeae1cd4596401e2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Nicol=C3=B2=20Boschi?= Date: Fri, 27 Mar 2026 10:58:42 +0100 Subject: [PATCH] docs: add AG2 integration page (#723) - Add AG2 integration doc with quick start, configuration, GroupChat example, and API reference - Add to sidebar, versioned sidebar, and integrations hub - Add AG2 icon --- hindsight-docs/docs/sdks/integrations/ag2.md | 182 ++++++++++++++++++ hindsight-docs/sidebars.ts | 6 + hindsight-docs/src/data/integrations.json | 10 + hindsight-docs/static/img/icons/ag2.svg | 1 + .../version-0.4/sdks/integrations/ag2.md | 182 ++++++++++++++++++ .../version-0.4-sidebars.json | 8 + 6 files changed, 389 insertions(+) create mode 100644 hindsight-docs/docs/sdks/integrations/ag2.md create mode 100644 hindsight-docs/static/img/icons/ag2.svg create mode 100644 hindsight-docs/versioned_docs/version-0.4/sdks/integrations/ag2.md diff --git a/hindsight-docs/docs/sdks/integrations/ag2.md b/hindsight-docs/docs/sdks/integrations/ag2.md new file mode 100644 index 00000000..fc2c6e19 --- /dev/null +++ b/hindsight-docs/docs/sdks/integrations/ag2.md @@ -0,0 +1,182 @@ +--- +sidebar_position: 8 +--- + +# AG2 + +Persistent long-term memory for [AG2](https://ag2.ai) agents (community AutoGen fork). Give your agents retain/recall/reflect tools that persist across conversations. + +[View Changelog →](/changelog/integrations/ag2) + +## Features + +- **Drop-in Tools** — `register_hindsight_tools()` registers retain, recall, and reflect in one line +- **AG2-native** — Uses `Annotated` type hints compatible with AG2's `@register_for_llm` / `@register_for_execution` pattern +- **GroupChat Support** — Multiple agents can share a single memory bank +- **Selective Tools** — Include only the tools you need (`include_retain`, `include_recall`, `include_reflect`) +- **Simple Configuration** — Configure once globally or override per tool set + +## Installation + +```bash +pip install hindsight-ag2 +``` + +## Quick Start + +```python +from autogen import AssistantAgent, UserProxyAgent, LLMConfig +from hindsight_ag2 import register_hindsight_tools + +llm_config = LLMConfig(api_type="openai", model="gpt-4o-mini") + +with llm_config: + assistant = AssistantAgent( + name="assistant", + system_message="You are a helpful assistant with long-term memory.", + ) + user_proxy = UserProxyAgent( + name="user", + human_input_mode="NEVER", + ) + +# Register Hindsight memory tools on both agents +register_hindsight_tools( + assistant, user_proxy, + bank_id="my-bank", + hindsight_api_url="http://localhost:8888", +) + +# The assistant can now use hindsight_retain, hindsight_recall, hindsight_reflect +result = user_proxy.initiate_chat( + assistant, + message="Remember that I prefer Python over JavaScript.", +) +``` + +That's it. The assistant can now store and retrieve memories across conversations. + +## How It Works + +The integration provides three AG2-compatible tool functions backed by Hindsight's API: + +| Tool | Hindsight | What happens | +|------|-----------|--------------| +| `hindsight_retain(content)` | `retain(bank_id, content, ...)` | Content is stored. Hindsight extracts facts, entities, and relationships from the raw text. | +| `hindsight_recall(query)` | `recall(bank_id, query, ...)` | Hindsight runs semantic search, BM25, graph traversal, and reranking. Returns a numbered list of matching memories. | +| `hindsight_reflect(query)` | `reflect(bank_id, query, ...)` | Hindsight synthesizes a reasoned answer from all relevant memories, using the bank's disposition traits. | + +Tools are plain Python functions with `Annotated` type hints. AG2 uses these hints to generate the tool schema that the LLM sees. + +## Configuration + +### Global Configuration + +```python +from hindsight_ag2 import configure + +configure( + hindsight_api_url="http://localhost:8888", + api_key="your-key", # or set HINDSIGHT_API_KEY env var + budget="mid", # low / mid / high + max_tokens=4096, + tags=["source:ag2"], # default tags for retain +) +``` + +### Per-Tool Overrides + +Constructor arguments override global configuration: + +```python +from hindsight_ag2 import create_hindsight_tools + +tools = create_hindsight_tools( + bank_id="my-bank", + hindsight_api_url="http://localhost:8888", + budget="high", + max_tokens=8192, + tags=["team:alpha"], +) +``` + +## GroupChat with Shared Memory + +Multiple agents can share a single memory bank in a GroupChat: + +```python +from autogen import AssistantAgent, UserProxyAgent, GroupChat, GroupChatManager, LLMConfig +from hindsight_ag2 import register_hindsight_tools + +llm_config = LLMConfig(api_type="openai", model="gpt-4o-mini") + +with llm_config: + researcher = AssistantAgent(name="researcher", system_message="You research topics.") + writer = AssistantAgent(name="writer", system_message="You write content.") + executor = UserProxyAgent(name="executor", human_input_mode="NEVER") + +# All agents share the same memory bank +for agent in [researcher, writer]: + register_hindsight_tools(agent, executor, bank_id="team-memory") + +group_chat = GroupChat(agents=[researcher, writer, executor], messages=[]) +manager = GroupChatManager(groupchat=group_chat) +``` + +## Manual Registration + +For full control over how tools are registered: + +```python +from hindsight_ag2 import create_hindsight_tools + +tools = create_hindsight_tools( + bank_id="my-bank", + hindsight_api_url="http://localhost:8888", +) +for tool_fn in tools: + assistant.register_for_llm(description=tool_fn.__doc__)(tool_fn) + user_proxy.register_for_execution()(tool_fn) +``` + +## API Reference + +### Configuration + +| Function | Description | +|----------|-------------| +| `configure(...)` | Set global connection and default settings | +| `get_config()` | Get current configuration | +| `reset_config()` | Reset configuration to None | + +### create_hindsight_tools + +| Parameter | Default | Description | +|-----------|---------|-------------| +| `bank_id` | required | Hindsight memory bank ID | +| `client` | `None` | Pre-configured `Hindsight` client | +| `hindsight_api_url` | from config | Hindsight API URL | +| `api_key` | from config | API key | +| `budget` | `"mid"` | Recall/reflect budget (low/mid/high) | +| `max_tokens` | `4096` | Max tokens for recall results | +| `tags` | `None` | Tags applied when storing memories | +| `recall_tags` | `None` | Tags to filter when searching | +| `recall_tags_match` | `"any"` | Tag matching mode (any/all/any_strict/all_strict) | +| `retain_metadata` | `None` | Metadata dict for retain operations | +| `retain_document_id` | `None` | Document ID for retain (groups/upserts memories) | +| `recall_types` | `None` | Fact types to filter (world, experience, opinion, observation) | +| `recall_include_entities` | `False` | Include entity information in recall results | +| `reflect_context` | `None` | Additional context for reflect operations | +| `reflect_max_tokens` | `max_tokens` | Max tokens for reflect results | +| `reflect_response_schema` | `None` | JSON schema to constrain reflect output format | +| `reflect_tags` | `recall_tags` | Tags to filter memories used in reflect | +| `reflect_tags_match` | `recall_tags_match` | Tag matching for reflect | +| `include_retain` | `True` | Include the retain tool | +| `include_recall` | `True` | Include the recall tool | +| `include_reflect` | `True` | Include the reflect tool | + +## Requirements + +- Python >= 3.10 +- ag2 >= 0.9.0 +- A running Hindsight API server diff --git a/hindsight-docs/sidebars.ts b/hindsight-docs/sidebars.ts index e0a10bfa..07ca4441 100644 --- a/hindsight-docs/sidebars.ts +++ b/hindsight-docs/sidebars.ts @@ -250,6 +250,12 @@ const sidebars: SidebarsConfig = { label: 'Strands Agents', customProps: { icon: '/img/icons/strands.png' }, }, + { + type: 'doc', + id: 'sdks/integrations/ag2', + label: 'AG2', + customProps: { icon: '/img/icons/ag2.svg' }, + }, { type: 'doc', id: 'sdks/integrations/skills', diff --git a/hindsight-docs/src/data/integrations.json b/hindsight-docs/src/data/integrations.json index c4889dc0..de0dfbc5 100644 --- a/hindsight-docs/src/data/integrations.json +++ b/hindsight-docs/src/data/integrations.json @@ -140,6 +140,16 @@ "link": "/sdks/integrations/strands", "icon": "/img/icons/strands.png" }, + { + "id": "ag2", + "name": "AG2", + "description": "Persistent long-term memory for AG2 agents with retain, recall, and reflect tools across conversations.", + "type": "official", + "by": "hindsight", + "category": "framework", + "link": "/sdks/integrations/ag2", + "icon": "/img/icons/ag2.svg" + }, { "id": "hindclaw", "name": "HindClaw", diff --git a/hindsight-docs/static/img/icons/ag2.svg b/hindsight-docs/static/img/icons/ag2.svg new file mode 100644 index 00000000..d6850b59 --- /dev/null +++ b/hindsight-docs/static/img/icons/ag2.svg @@ -0,0 +1 @@ + \ No newline at end of file diff --git a/hindsight-docs/versioned_docs/version-0.4/sdks/integrations/ag2.md b/hindsight-docs/versioned_docs/version-0.4/sdks/integrations/ag2.md new file mode 100644 index 00000000..fc2c6e19 --- /dev/null +++ b/hindsight-docs/versioned_docs/version-0.4/sdks/integrations/ag2.md @@ -0,0 +1,182 @@ +--- +sidebar_position: 8 +--- + +# AG2 + +Persistent long-term memory for [AG2](https://ag2.ai) agents (community AutoGen fork). Give your agents retain/recall/reflect tools that persist across conversations. + +[View Changelog →](/changelog/integrations/ag2) + +## Features + +- **Drop-in Tools** — `register_hindsight_tools()` registers retain, recall, and reflect in one line +- **AG2-native** — Uses `Annotated` type hints compatible with AG2's `@register_for_llm` / `@register_for_execution` pattern +- **GroupChat Support** — Multiple agents can share a single memory bank +- **Selective Tools** — Include only the tools you need (`include_retain`, `include_recall`, `include_reflect`) +- **Simple Configuration** — Configure once globally or override per tool set + +## Installation + +```bash +pip install hindsight-ag2 +``` + +## Quick Start + +```python +from autogen import AssistantAgent, UserProxyAgent, LLMConfig +from hindsight_ag2 import register_hindsight_tools + +llm_config = LLMConfig(api_type="openai", model="gpt-4o-mini") + +with llm_config: + assistant = AssistantAgent( + name="assistant", + system_message="You are a helpful assistant with long-term memory.", + ) + user_proxy = UserProxyAgent( + name="user", + human_input_mode="NEVER", + ) + +# Register Hindsight memory tools on both agents +register_hindsight_tools( + assistant, user_proxy, + bank_id="my-bank", + hindsight_api_url="http://localhost:8888", +) + +# The assistant can now use hindsight_retain, hindsight_recall, hindsight_reflect +result = user_proxy.initiate_chat( + assistant, + message="Remember that I prefer Python over JavaScript.", +) +``` + +That's it. The assistant can now store and retrieve memories across conversations. + +## How It Works + +The integration provides three AG2-compatible tool functions backed by Hindsight's API: + +| Tool | Hindsight | What happens | +|------|-----------|--------------| +| `hindsight_retain(content)` | `retain(bank_id, content, ...)` | Content is stored. Hindsight extracts facts, entities, and relationships from the raw text. | +| `hindsight_recall(query)` | `recall(bank_id, query, ...)` | Hindsight runs semantic search, BM25, graph traversal, and reranking. Returns a numbered list of matching memories. | +| `hindsight_reflect(query)` | `reflect(bank_id, query, ...)` | Hindsight synthesizes a reasoned answer from all relevant memories, using the bank's disposition traits. | + +Tools are plain Python functions with `Annotated` type hints. AG2 uses these hints to generate the tool schema that the LLM sees. + +## Configuration + +### Global Configuration + +```python +from hindsight_ag2 import configure + +configure( + hindsight_api_url="http://localhost:8888", + api_key="your-key", # or set HINDSIGHT_API_KEY env var + budget="mid", # low / mid / high + max_tokens=4096, + tags=["source:ag2"], # default tags for retain +) +``` + +### Per-Tool Overrides + +Constructor arguments override global configuration: + +```python +from hindsight_ag2 import create_hindsight_tools + +tools = create_hindsight_tools( + bank_id="my-bank", + hindsight_api_url="http://localhost:8888", + budget="high", + max_tokens=8192, + tags=["team:alpha"], +) +``` + +## GroupChat with Shared Memory + +Multiple agents can share a single memory bank in a GroupChat: + +```python +from autogen import AssistantAgent, UserProxyAgent, GroupChat, GroupChatManager, LLMConfig +from hindsight_ag2 import register_hindsight_tools + +llm_config = LLMConfig(api_type="openai", model="gpt-4o-mini") + +with llm_config: + researcher = AssistantAgent(name="researcher", system_message="You research topics.") + writer = AssistantAgent(name="writer", system_message="You write content.") + executor = UserProxyAgent(name="executor", human_input_mode="NEVER") + +# All agents share the same memory bank +for agent in [researcher, writer]: + register_hindsight_tools(agent, executor, bank_id="team-memory") + +group_chat = GroupChat(agents=[researcher, writer, executor], messages=[]) +manager = GroupChatManager(groupchat=group_chat) +``` + +## Manual Registration + +For full control over how tools are registered: + +```python +from hindsight_ag2 import create_hindsight_tools + +tools = create_hindsight_tools( + bank_id="my-bank", + hindsight_api_url="http://localhost:8888", +) +for tool_fn in tools: + assistant.register_for_llm(description=tool_fn.__doc__)(tool_fn) + user_proxy.register_for_execution()(tool_fn) +``` + +## API Reference + +### Configuration + +| Function | Description | +|----------|-------------| +| `configure(...)` | Set global connection and default settings | +| `get_config()` | Get current configuration | +| `reset_config()` | Reset configuration to None | + +### create_hindsight_tools + +| Parameter | Default | Description | +|-----------|---------|-------------| +| `bank_id` | required | Hindsight memory bank ID | +| `client` | `None` | Pre-configured `Hindsight` client | +| `hindsight_api_url` | from config | Hindsight API URL | +| `api_key` | from config | API key | +| `budget` | `"mid"` | Recall/reflect budget (low/mid/high) | +| `max_tokens` | `4096` | Max tokens for recall results | +| `tags` | `None` | Tags applied when storing memories | +| `recall_tags` | `None` | Tags to filter when searching | +| `recall_tags_match` | `"any"` | Tag matching mode (any/all/any_strict/all_strict) | +| `retain_metadata` | `None` | Metadata dict for retain operations | +| `retain_document_id` | `None` | Document ID for retain (groups/upserts memories) | +| `recall_types` | `None` | Fact types to filter (world, experience, opinion, observation) | +| `recall_include_entities` | `False` | Include entity information in recall results | +| `reflect_context` | `None` | Additional context for reflect operations | +| `reflect_max_tokens` | `max_tokens` | Max tokens for reflect results | +| `reflect_response_schema` | `None` | JSON schema to constrain reflect output format | +| `reflect_tags` | `recall_tags` | Tags to filter memories used in reflect | +| `reflect_tags_match` | `recall_tags_match` | Tag matching for reflect | +| `include_retain` | `True` | Include the retain tool | +| `include_recall` | `True` | Include the recall tool | +| `include_reflect` | `True` | Include the reflect tool | + +## Requirements + +- Python >= 3.10 +- ag2 >= 0.9.0 +- A running Hindsight API server diff --git a/hindsight-docs/versioned_sidebars/version-0.4-sidebars.json b/hindsight-docs/versioned_sidebars/version-0.4-sidebars.json index f5c9524a..256f8fab 100644 --- a/hindsight-docs/versioned_sidebars/version-0.4-sidebars.json +++ b/hindsight-docs/versioned_sidebars/version-0.4-sidebars.json @@ -323,6 +323,14 @@ "icon": "/img/icons/strands.png" } }, + { + "type": "doc", + "id": "sdks/integrations/ag2", + "label": "AG2", + "customProps": { + "icon": "/img/icons/ag2.svg" + } + }, { "type": "doc", "id": "sdks/integrations/skills",