From bbb7980fee27a8c28ee51e6aa6fcfbc09a79bda6 Mon Sep 17 00:00:00 2001 From: ajspig Date: Thu, 22 Jan 2026 16:26:36 -0500 Subject: [PATCH] fix: minor clarifications --- examples/agno/python/README.md | 60 +++++++++---------- .../agno/python/examples/simple_example.py | 17 ++---- .../agno/python/src/honcho_agno/__init__.py | 38 ++++++------ examples/agno/python/src/honcho_agno/tools.py | 25 ++++---- 4 files changed, 66 insertions(+), 74 deletions(-) diff --git a/examples/agno/python/README.md b/examples/agno/python/README.md index a19497d3..e352833c 100644 --- a/examples/agno/python/README.md +++ b/examples/agno/python/README.md @@ -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 diff --git a/examples/agno/python/examples/simple_example.py b/examples/agno/python/examples/simple_example.py index 41380147..0f03ffb7 100644 --- a/examples/agno/python/examples/simple_example.py +++ b/examples/agno/python/examples/simple_example.py @@ -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) diff --git a/examples/agno/python/src/honcho_agno/__init__.py b/examples/agno/python/src/honcho_agno/__init__.py index 7ad42d30..198d07b1 100644 --- a/examples/agno/python/src/honcho_agno/__init__.py +++ b/examples/agno/python/src/honcho_agno/__init__.py @@ -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))]) ``` """ diff --git a/examples/agno/python/src/honcho_agno/tools.py b/examples/agno/python/src/honcho_agno/tools.py index b1b4e3ab..f0c69fb5 100644 --- a/examples/agno/python/src/honcho_agno/tools.py +++ b/examples/agno/python/src/honcho_agno/tools.py @@ -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)