RomanNum3ral
/
honcho
mirror of https://github.com/plastic-labs/honcho.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

fix: minor clarifications

This commit is contained in:
ajspig 2026-01-22 16:26:36 -05:00
parent 23e64cd90a
commit bbb7980fee
4 changed files with 66 additions and 74 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

60
examples/agno/python/README.md
View File

@ -26,35 +26,31 @@ from honcho_agno import HonchoTools
honcho = Honcho(workspace_id="my-app")
# Create Honcho tools for the agent
honcho_tools = HonchoTools(
agent_id="assistant",
honcho_client=honcho,
)
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],
description="An assistant with persistent memory powered by Honcho.",
)
# Create peers and session for orchestration
# Create peers and session for message persistence
user_peer = honcho.peer("user-123")
assistant_peer = honcho.peer("assistant")
session = honcho.session("session-123")
# Add user message via orchestration
# 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
# 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 via orchestration
# Save assistant response
session.add_messages([assistant_peer.message(str(response.content))])
```
@ -65,10 +61,23 @@ HonchoTools maps to Agno's user/assistant architecture:
| Agno Concept | Honcho Concept | Description |
|--------------|----------------|-------------|
| `user_id` (from RunContext) | Peer | The human user being queried about |
| `agent_id` (from init) | Peer | The AI assistant's identity |
| `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 `context.user_id`.
**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
@ -91,11 +100,8 @@ from honcho_agno import HonchoTools
# Create shared Honcho client
honcho = Honcho(workspace_id="my-app")
# Create toolkit for an agent
tools = HonchoTools(
agent_id="assistant", # Agent's identity in Honcho
honcho_client=honcho, # Shared Honcho client
)
# Create toolkit
tools = HonchoTools(honcho_client=honcho)
```
### Without Pre-configured Client
@ -104,18 +110,13 @@ tools = HonchoTools(
from honcho_agno import HonchoTools
# Creates its own Honcho client internally
tools = HonchoTools(
workspace_id="my-app", # Workspace ID (used to create internal client)
agent_id="assistant", # Agent's identity
)
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
Configure via `.env` file in the root honcho directory:
**Honcho Settings:**
- `HONCHO_ENVIRONMENT`: `local` or `production` (default: production)
@ -124,7 +125,7 @@ Configure via `.env` file in the root honcho directory:
**OpenAI Settings (for examples):**
- `OPENAI_API_KEY` or `LLM_OPENAI_API_KEY`: OpenAI API key
- `OPENAI_API_KEY`: OpenAI API key
- `OPENAI_MODEL`: Model to use (default: gpt-4o)
## Tool Details
@ -163,26 +164,26 @@ Agno Teams share context within a run, but what about across runs? What if Agent
```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
# 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_tools = HonchoTools(agent_id="tech-advisor", honcho_client=honcho)
tech_agent = Agent(
name="Tech Advisor",
model=OpenAIChat(id="gpt-4o"),
tools=[tech_tools],
tools=[honcho_tools],
)
# Business advisor with Honcho memory
biz_tools = HonchoTools(agent_id="biz-advisor", honcho_client=honcho)
biz_agent = Agent(
name="Business Advisor",
model=OpenAIChat(id="gpt-4o"),
tools=[biz_tools],
tools=[honcho_tools],
)
# Create team
@ -211,8 +212,7 @@ response = team.run(
See the [examples](./examples) directory for complete working examples:
- `simple_example.py`: Basic usage with HonchoTools
- `multi_tool_example.py`: Using all tools together
- `simple_example.py`: Basic usage with HonchoTools demonstrating memory persistence and context retrieval
## Development

17
examples/agno/python/examples/simple_example.py
View File

@ -4,11 +4,11 @@ Simple Honcho + Agno Example
Demonstrates the RunContext integration:
- user_id and session_id are passed to agent.run()
- Tools automatically receive RunContext with these values
- Orchestration uses the honcho client directly
- Orchestration uses the honcho client directly for message persistence
Environment Variables:
LLM_OPENAI_API_KEY: OpenAI API key (matches honcho .env)
HONCHO_API_KEY: Required for Honcho API access
OPENAI_API_KEY: OpenAI API key
HONCHO_API_KEY: Required for Honcho API access (production)
"""
import os
@ -25,10 +25,6 @@ from honcho_agno import HonchoTools
load_dotenv()
# Use LLM_OPENAI_API_KEY from honcho .env
if llm_key := os.getenv("LLM_OPENAI_API_KEY"):
os.environ["OPENAI_API_KEY"] = llm_key
def main():
# Unique IDs for this run
@ -38,12 +34,9 @@ def main():
# Initialize Honcho client
honcho = Honcho(workspace_id="agno-demo")
# Initialize HonchoTools with agent identity
# Initialize HonchoTools
# user_id and session_id come from RunContext at runtime
honcho_tools = HonchoTools(
agent_id="assistant",
honcho_client=honcho,
)
honcho_tools = HonchoTools(honcho_client=honcho)
# Create peers and session for orchestration
user_peer = honcho.peer(user_id)

38
examples/agno/python/src/honcho_agno/__init__.py
View File

@ -4,9 +4,8 @@ Honcho Agno Integration
This package provides seamless integration between Honcho and Agno,
enabling AI agents to maintain persistent memory across conversations.
Each HonchoTools instance represents ONE agent identity (peer). The toolkit
provides read access to Honcho for querying conversation context.
Orchestration code handles saving messages to avoid duplicates.
The toolkit provides read access to Honcho for querying conversation context.
Orchestration code handles saving messages using the Honcho client directly.
Example:
```python
@ -15,35 +14,36 @@ Example:
from honcho import Honcho
from honcho_agno import HonchoTools
# Shared Honcho client
# Initialize Honcho client
honcho = Honcho(workspace_id="my-app")
# Create Honcho tools for the assistant
honcho_tools = HonchoTools(
peer_id="assistant",
session_id="session-123",
honcho_client=honcho,
)
# Create Honcho tools for the agent
honcho_tools = HonchoTools(honcho_client=honcho)
# Create user peer for orchestration
user_peer = honcho.peer("user")
# Create peers and session for orchestration
user_peer = honcho.peer("user-123")
assistant_peer = honcho.peer("assistant")
session = honcho.session("session-123")
# Create agent with memory
# Create agent with memory tools
agent = Agent(
name="Memory Agent",
model=OpenAIChat(id="gpt-4o"),
tools=[honcho_tools],
description="An assistant with persistent memory powered by Honcho.",
)
# Save user message via orchestration
honcho_tools.session.add_messages([user_peer.message("I prefer Python over JavaScript")])
# Save user message via orchestration (using honcho client directly)
session.add_messages([user_peer.message("I prefer Python over JavaScript")])
# Run the agent
response = agent.run("What programming language does the user prefer?")
# Run 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 via orchestration
honcho_tools.session.add_messages([honcho_tools.peer.message(str(response.content))])
session.add_messages([assistant_peer.message(str(response.content))])
```
"""

25
examples/agno/python/src/honcho_agno/tools.py
View File

@ -6,12 +6,15 @@ memory system, including session context, semantic search, and chat.
Designed for Agno's user/assistant architecture:
- user_id from RunContext → Honcho peer (the human user)
- agent_id from init → Honcho peer (the AI assistant)
- session_id from RunContext → Honcho session (shared conversation)
Cross-run memory: Unlike Agno Teams which only share context within a run,
Honcho persists memory across runs. Agent A can remember what Agent B
learned last week.
Message Persistence: This toolkit is READ-ONLY. To save messages, use the
Honcho client directly in your orchestration code:
session.add_messages([user_peer.message("..."), assistant_peer.message("...")])
"""
import logging
@ -29,24 +32,25 @@ class HonchoTools(Toolkit):
Maps to Agno's user/assistant model:
- user_id from RunContext → Honcho peer (the human being queried about)
- agent_id from init → Honcho peer (the AI assistant's identity)
- session_id from RunContext → Honcho session (the conversation)
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.
This toolkit is READ-ONLY. To persist messages, use the Honcho client
directly in your orchestration code (see simple_example.py).
Example:
```python
from agno.agent import Agent
from agno.models.openai import OpenAIChat
from honcho import Honcho
from honcho_agno import HonchoTools
# Initialize toolkit with agent identity
honcho_tools = HonchoTools(
workspace_id="my-app",
agent_id="travel-assistant",
)
# Initialize Honcho client and toolkit
honcho = Honcho(workspace_id="my-app")
honcho_tools = HonchoTools(honcho_client=honcho)
agent = Agent(
model=OpenAIChat(id="gpt-4o"),
@ -61,17 +65,14 @@ class HonchoTools(Toolkit):
def __init__(
self,
workspace_id: str = "default",
agent_id: str = "assistant",
honcho_client: Honcho | None = None,
) -> None:
"""
Initialize the Honcho toolkit for a specific agent identity.
Initialize the Honcho toolkit.
Args:
workspace_id: Workspace ID for creating an internal Honcho client.
Ignored if honcho_client is provided.
agent_id: The agent's identity in Honcho. Used for message attribution
when the orchestration code saves messages.
honcho_client: Optional pre-configured Honcho client instance.
When provided, uses this client directly (workspace_id is ignored).
"""
@ -83,8 +84,6 @@ class HonchoTools(Toolkit):
else:
self.honcho = Honcho(workspace_id=workspace_id)
self.agent_id: str = agent_id
# Register tools with honcho_ prefix to avoid conflicts with other toolkits
self.register(self.honcho_get_context)
self.register(self.honcho_search_messages)