241 lines
6.1 KiB
Markdown
241 lines
6.1 KiB
Markdown
# Honcho Agno Integration
|
|
|
|
Give your [Agno](https://agno.com) agents persistent memory with [Honcho](https://honcho.dev).
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
pip install honcho-agno
|
|
```
|
|
|
|
Or with uv:
|
|
|
|
```bash
|
|
uv add honcho-agno
|
|
```
|
|
|
|
## Quick Start
|
|
|
|
```python
|
|
from agno.agent import Agent
|
|
from agno.models.openai import OpenAIChat
|
|
from honcho import Honcho
|
|
from honcho_agno import HonchoTools
|
|
|
|
# Initialize Honcho client
|
|
honcho = Honcho(workspace_id="my-app")
|
|
|
|
# Create Honcho tools for the agent
|
|
honcho_tools = HonchoTools(honcho_client=honcho)
|
|
|
|
# Create an agent with memory tools
|
|
agent = Agent(
|
|
name="Memory Agent",
|
|
model=OpenAIChat(id="gpt-4o"),
|
|
tools=[honcho_tools],
|
|
)
|
|
|
|
# Create peers and session for message persistence
|
|
user_peer = honcho.peer("user-123")
|
|
assistant_peer = honcho.peer("assistant")
|
|
session = honcho.session("session-123")
|
|
|
|
# Save user message (orchestration handles persistence)
|
|
session.add_messages([user_peer.message("I prefer Python over JavaScript")])
|
|
|
|
# Run the agent - user_id and session_id flow through RunContext to tools
|
|
response = agent.run(
|
|
"What programming language does the user prefer?",
|
|
user_id="user-123",
|
|
session_id="session-123",
|
|
)
|
|
|
|
# Save assistant response
|
|
session.add_messages([assistant_peer.message(str(response.content))])
|
|
```
|
|
|
|
## How It Works
|
|
|
|
HonchoTools maps to Agno's user/assistant architecture:
|
|
|
|
| Agno Concept | Honcho Concept | Description |
|
|
|--------------|----------------|-------------|
|
|
| `user_id` (from RunContext) | Peer | The human user being queried about |
|
|
| `session_id` (from RunContext) | Session | The conversation context |
|
|
|
|
**Key insight**: Tools query Honcho about the **USER**, not the agent. When the agent asks "What does this user prefer?", Honcho returns insights about the human user identified by `run_context.user_id`.
|
|
|
|
### Message Persistence
|
|
|
|
This toolkit is **read-only** - it provides tools for querying Honcho's memory but does not automatically save messages. Your orchestration code handles message persistence using the Honcho client directly:
|
|
|
|
```python
|
|
# Save messages using the Honcho client (not the toolkit)
|
|
session.add_messages([
|
|
user_peer.message("User's message"),
|
|
assistant_peer.message("Assistant's response"),
|
|
])
|
|
```
|
|
|
|
This separation gives you explicit control over what gets saved to memory.
|
|
|
|
## Features
|
|
|
|
The `HonchoTools` toolkit provides three memory tools:
|
|
|
|
| Tool | Description |
|
|
|------|-------------|
|
|
| `honcho_get_context` | Retrieve conversation context within token limits |
|
|
| `honcho_search_messages` | Semantic search through past messages |
|
|
| `honcho_chat` | Query Honcho for synthesized insights about the user |
|
|
|
|
## Configuration
|
|
|
|
### Basic Configuration
|
|
|
|
```python
|
|
from honcho import Honcho
|
|
from honcho_agno import HonchoTools
|
|
|
|
# Create shared Honcho client
|
|
honcho = Honcho(workspace_id="my-app")
|
|
|
|
# Create toolkit
|
|
tools = HonchoTools(honcho_client=honcho)
|
|
```
|
|
|
|
### Without Pre-configured Client
|
|
|
|
```python
|
|
from honcho_agno import HonchoTools
|
|
|
|
# Creates its own Honcho client internally
|
|
tools = HonchoTools(workspace_id="my-app")
|
|
```
|
|
|
|
Note: When `honcho_client` is provided, `workspace_id` is ignored since the client already has its workspace configured.
|
|
|
|
### Environment Variables
|
|
|
|
**Honcho Settings:**
|
|
|
|
- `HONCHO_ENVIRONMENT`: `local` or `production` (default: production)
|
|
- `HONCHO_API_KEY`: API key for production environment
|
|
- `HONCHO_WORKSPACE_ID`: Default workspace ID
|
|
|
|
**OpenAI Settings (for examples):**
|
|
|
|
- `OPENAI_API_KEY`: OpenAI API key
|
|
- `OPENAI_MODEL`: Model to use (default: gpt-4o)
|
|
|
|
## Tool Details
|
|
|
|
### honcho_get_context
|
|
|
|
Retrieve recent conversation context. Uses `session_id` from RunContext.
|
|
|
|
```python
|
|
# Called by the agent automatically with RunContext
|
|
# Or call directly with a mock context for testing
|
|
```
|
|
|
|
### honcho_search_messages
|
|
|
|
Search through past messages semantically. Uses `session_id` from RunContext.
|
|
|
|
```python
|
|
# Called by the agent automatically with RunContext
|
|
# Query example: "programming preferences"
|
|
```
|
|
|
|
### honcho_chat
|
|
|
|
Ask questions about the user using Honcho's reasoning. Uses both `user_id` and `session_id` from RunContext.
|
|
|
|
```python
|
|
# Called by the agent automatically with RunContext
|
|
# Query example: "What programming languages does the user prefer?"
|
|
```
|
|
|
|
## Multi-Agent Systems (Teams)
|
|
|
|
Agno Teams share context within a run, but what about across runs? What if Agent A needs to remember what Agent B learned last week? That's where Honcho comes in.
|
|
|
|
```python
|
|
from agno.agent import Agent
|
|
from agno.team import Team
|
|
from agno.models.openai import OpenAIChat
|
|
from honcho import Honcho
|
|
from honcho_agno import HonchoTools
|
|
|
|
# Shared Honcho client - all agents share the same memory
|
|
honcho = Honcho(workspace_id="advisory-app")
|
|
honcho_tools = HonchoTools(honcho_client=honcho)
|
|
|
|
# Tech advisor with Honcho memory
|
|
tech_agent = Agent(
|
|
name="Tech Advisor",
|
|
model=OpenAIChat(id="gpt-4o"),
|
|
tools=[honcho_tools],
|
|
)
|
|
|
|
# Business advisor with Honcho memory
|
|
biz_agent = Agent(
|
|
name="Business Advisor",
|
|
model=OpenAIChat(id="gpt-4o"),
|
|
tools=[honcho_tools],
|
|
)
|
|
|
|
# Create team
|
|
team = Team(
|
|
name="Advisory Team",
|
|
agents=[tech_agent, biz_agent],
|
|
)
|
|
|
|
# Run with shared user_id and session_id
|
|
# Both agents query Honcho about the same user
|
|
response = team.run(
|
|
"How should I scale my startup?",
|
|
user_id="founder-123",
|
|
session_id="strategy-session",
|
|
)
|
|
```
|
|
|
|
## Architecture Notes
|
|
|
|
- **Read-only toolkit**: `HonchoTools` provides read access to Honcho (context, search, chat)
|
|
- **Orchestration pattern**: Message saving is handled by your orchestration code using `honcho.session().add_messages()`
|
|
- **RunContext integration**: `user_id` and `session_id` flow through Agno's RunContext automatically
|
|
- **Cross-run memory**: Unlike Agno Teams (context within a run), Honcho persists memory across runs
|
|
|
|
## Examples
|
|
|
|
See the [examples](./examples) directory for complete working examples:
|
|
|
|
- `simple_example.py`: Basic usage with HonchoTools demonstrating memory persistence and context retrieval
|
|
|
|
## Development
|
|
|
|
### Setup
|
|
|
|
```bash
|
|
cd examples/agno/python
|
|
uv sync
|
|
```
|
|
|
|
### Run Tests
|
|
|
|
```bash
|
|
uv run pytest
|
|
```
|
|
|
|
### Run Examples
|
|
|
|
```bash
|
|
uv run python examples/simple_example.py
|
|
```
|
|
|
|
## License
|
|
|
|
AGPL-3.0-or-later
|