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
This commit is contained in:
Nicolò Boschi
GitHub
parent
9321c59bf1
commit
3c78b717b0
6 changed files with 389 additions and 0 deletions
182
hindsight-docs/docs/sdks/integrations/ag2.md
Normal file
182
hindsight-docs/docs/sdks/integrations/ag2.md
Normal file
|
|
@ -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
|
||||
|
|
@ -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',
|
||||
|
|
|
|||
|
|
@ -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",
|
||||
|
|
|
|||
1
hindsight-docs/static/img/icons/ag2.svg
Normal file
1
hindsight-docs/static/img/icons/ag2.svg
Normal file
|
|
@ -0,0 +1 @@
|
|||
<svg xmlns="http://www.w3.org/2000/svg" width="32" height="32" fill="none"><g fill="#000" clip-path="url(#a)"><path d="M32 0h-2.142v2.142H32V0Zm-2.142 10.667H27.73v4.269h2.128v-4.27Zm0-8.525H27.73v2.127h2.128V2.142ZM27.73 8.539h-2.127v2.128h2.127V8.539Zm0-4.269h-2.127v2.14h2.127V4.27Zm-2.127 2.141h-4.27V8.54h4.27V6.41Zm-4.27-2.141H10.667v2.14h10.666V4.27Zm4.27 12.794v-4.256H23.46v-2.141H8.54v2.141H6.397v4.256h19.206Zm-6.397-4.256h2.127v2.128h-2.127v-2.128Zm-8.54 0h2.128v2.128h-2.127v-2.128Zm.001-6.397h-4.27V8.54h4.27V6.41Zm-4.27 2.128H4.27v2.128h2.127V8.539Zm0-4.269H4.27v2.14h2.127V4.27ZM4.27 10.667H2.142v4.269H4.27v-4.27Zm0-8.525H2.142v2.127H4.27V2.142ZM2.142 0H0v2.142h2.142V0Zm27.593 25.017v-2.265h-6.794v-2.265h6.794v2.265H32v2.265h-2.265Zm-4.53 2.265v-2.265h4.53v2.265h-4.53Zm-2.264 4.53v-4.53h2.265v2.264H32v2.265h-9.06Zm-9.206-9.06v-2.265h6.795v2.265h-6.795Zm-2.264 6.794v-6.794h2.264v6.794h-2.264Zm6.794 0v-2.264H16v-2.265h4.53v4.53h-2.265Zm-4.53 2.265v-2.265h4.53v2.265h-4.53ZM0 31.811v-9.059h2.265v-2.265h4.53v2.265h2.264v9.06H6.794v-4.53h-4.53v4.53H0Zm2.265-6.794h4.53v-2.174h-4.53v2.174Z"/></g><defs><clipPath id="a"><path fill="#fff" d="M0 0h32v32H0z"/></clipPath></defs></svg>
|
||||
|
After Width: | Height: | Size: 1.2 KiB |
|
|
@ -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
|
||||
|
|
@ -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",
|
||||
|
|
|
|||
Loading…
Reference in a new issue