feat: add AgentOSClient class and cookbooks

cookbook/agent_os/client/01_basic_client.py

@@ -0,0 +1,52 @@
+"""
+Basic AgentOSClient Example
+
+This example demonstrates how to use AgentOSClient to connect to
+a remote AgentOS instance and perform basic operations.
+
+Prerequisites:
+1. Start an AgentOS server:
+   python -c "
+   from agno.agent import Agent
+   from agno.models.openai import OpenAIChat
+   from agno.os import AgentOS
+
+   agent = Agent(
+       name='Assistant',
+       model=OpenAIChat(id='gpt-4o-mini'),
+       instructions='You are a helpful assistant.',
+   )
+   agent_os = AgentOS(agents=[agent])
+   agent_os.serve()
+   "
+
+2. Run this script: python 01_basic_client.py
+"""
+
+import asyncio
+
+from agno.os.client import AgentOSClient
+
+
+async def main():
+    # Connect to AgentOS using async context manager
+    async with AgentOSClient(base_url="http://localhost:7777") as client:
+        # Get AgentOS configuration
+        config = await client.get_config()
+        print(f"Connected to: {config.name or config.os_id}")
+        print(f"Available agents: {[a.id for a in (config.agents or [])]}")
+        print(f"Available teams: {[t.id for t in (config.teams or [])]}")
+        print(f"Available workflows: {[w.id for w in (config.workflows or [])]}")
+
+        # Get details about a specific agent
+        if config.agents:
+            agent_id = config.agents[0].id
+            agent = await client.get_agent(agent_id)
+            print("\nAgent Details:")
+            print(f"  Name: {agent.name}")
+            print(f"  Model: {agent.model}")
+            print(f"  Tools: {len(agent.tools or [])}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

cookbook/agent_os/client/02_run_agents.py

@@ -0,0 +1,135 @@
+"""
+Running Agents with AgentOSClient
+
+This example demonstrates how to execute agent runs using
+AgentOSClient, including both streaming and non-streaming responses.
+
+Prerequisites:
+1. Start an AgentOS server with an agent
+2. Run this script: python 02_run_agents.py
+"""
+
+import asyncio
+import json
+
+from agno.os.client import AgentOSClient
+
+
+async def run_agent_non_streaming():
+    """Execute a non-streaming agent run."""
+    print("=" * 60)
+    print("Non-Streaming Agent Run")
+    print("=" * 60)
+
+    async with AgentOSClient(base_url="http://localhost:7777") as client:
+        # Get available agents
+        config = await client.get_config()
+        if not config.agents:
+            print("No agents available")
+            return
+
+        agent_id = config.agents[0].id
+        print(f"Running agent: {agent_id}")
+
+        # Execute the agent
+        result = await client.run_agent(
+            agent_id=agent_id,
+            message="What is 2 + 2? Explain your answer briefly.",
+        )
+
+        print(f"\nRun ID: {result.run_id}")
+        print(f"Content: {result.content}")
+        print(
+            f"Tokens: {result.metrics.get('total_tokens') if result.metrics else 'N/A'}"
+        )
+
+
+async def run_agent_streaming():
+    """Execute a streaming agent run."""
+    print("\n" + "=" * 60)
+    print("Streaming Agent Run")
+    print("=" * 60)
+
+    async with AgentOSClient(base_url="http://localhost:7777") as client:
+        # Get available agents
+        config = await client.get_config()
+        if not config.agents:
+            print("No agents available")
+            return
+
+        agent_id = config.agents[0].id
+        print(f"Streaming from agent: {agent_id}")
+        print("\nResponse: ", end="", flush=True)
+
+        # Stream the response
+        full_content = ""
+        async for line in client.stream_agent_run(
+            agent_id=agent_id,
+            message="Tell me a short joke.",
+        ):
+            if line.startswith("data: "):
+                try:
+                    data = json.loads(line[6:])
+                    if data.get("event") == "RunContent":
+                        content = data.get("content", "")
+                        print(content, end="", flush=True)
+                        full_content += content
+                except json.JSONDecodeError as e:
+                    print(f"Warning: Failed to decode JSON from line: {line[6:]}. Error: {e}")
+
+        print("\n")
+
+
+async def run_agent_with_session():
+    """Execute agent runs within a session for multi-turn conversations."""
+    print("=" * 60)
+    print("Multi-Turn Conversation with Session")
+    print("=" * 60)
+
+    async with AgentOSClient(base_url="http://localhost:7777") as client:
+        # Get available agents
+        config = await client.get_config()
+        if not config.agents:
+            print("No agents available")
+            return
+
+        agent_id = config.agents[0].id
+
+        # Create a session for multi-turn conversation
+        session = await client.create_session(
+            agent_id=agent_id,
+            user_id="example-user",
+        )
+        print(f"Created session: {session.session_id}")
+
+        # First message
+        print("\nUser: My name is Alice.")
+        result1 = await client.run_agent(
+            agent_id=agent_id,
+            message="My name is Alice.",
+            session_id=session.session_id,
+        )
+        print(f"Assistant: {result1.content}")
+
+        # Second message - agent should remember the context
+        print("\nUser: What is my name?")
+        result2 = await client.run_agent(
+            agent_id=agent_id,
+            message="What is my name?",
+            session_id=session.session_id,
+        )
+        print(f"Assistant: {result2.content}")
+
+        # Get session runs
+        runs = await client.get_session_runs(session_id=session.session_id)
+        print(f"\nSession has {len(runs)} runs")
+
+
+async def main():
+    await run_agent_non_streaming()
+    await run_agent_streaming()
+    await run_agent_with_session()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

cookbook/agent_os/client/03_memory_operations.py

@@ -0,0 +1,87 @@
+"""
+Memory Operations with AgentOSClient
+
+This example demonstrates how to manage user memories using
+AgentOSClient.
+
+Prerequisites:
+1. Start an AgentOS server with an agent that has enable_user_memories=True
+2. Run this script: python 03_memory_operations.py
+"""
+
+import asyncio
+
+from agno.os.client import AgentOSClient
+
+
+async def main():
+    async with AgentOSClient(base_url="http://localhost:7777") as client:
+        user_id = "example-user"
+
+        print("=" * 60)
+        print("Memory Operations")
+        print("=" * 60)
+
+        # Create a memory
+        print("\n1. Creating a memory...")
+        memory = await client.create_memory(
+            memory="User prefers dark mode for all applications",
+            user_id=user_id,
+            topics=["preferences", "ui"],
+        )
+        print(f"   Created memory: {memory.memory_id}")
+        print(f"   Content: {memory.memory}")
+        print(f"   Topics: {memory.topics}")
+
+        # List memories for the user
+        print("\n2. Listing memories...")
+        memories = await client.list_memories(user_id=user_id)
+        print(f"   Found {len(memories.data)} memories for user {user_id}")
+        for mem in memories.data:
+            print(f"   - {mem.memory_id}: {mem.memory[:50]}...")
+
+        # Get a specific memory
+        print(f"\n3. Getting memory {memory.memory_id}...")
+        retrieved = await client.get_memory(memory.memory_id, user_id=user_id)
+        print(f"   Memory: {retrieved.memory}")
+
+        # Update the memory
+        print("\n4. Updating memory...")
+        updated = await client.update_memory(
+            memory_id=memory.memory_id,
+            memory="User strongly prefers dark mode for all applications and websites",
+            user_id=user_id,
+            topics=["preferences", "ui", "accessibility"],
+        )
+        print(f"   Updated memory: {updated.memory}")
+        print(f"   Updated topics: {updated.topics}")
+
+        # Get memory topics (optional - may fail if not supported)
+        print("\n5. Getting all memory topics...")
+        try:
+            topics = await client.get_memory_topics()
+            print(f"   Topics: {topics}")
+        except Exception as e:
+            print(f"   Skipped (endpoint may not be available): {type(e).__name__}")
+
+        # Get user memory stats (optional - may fail if not supported)
+        print("\n6. Getting user memory stats...")
+        try:
+            stats = await client.get_user_memory_stats()
+            print(f"   Stats: {len(stats.data)} entries")
+        except Exception as e:
+            print(f"   Skipped (endpoint may not be available): {type(e).__name__}")
+
+        # Delete the memory
+        print(f"\n7. Deleting memory {memory.memory_id}...")
+        await client.delete_memory(memory.memory_id, user_id=user_id)
+        print("   Memory deleted")
+
+        # Verify deletion
+        print("\n8. Verifying deletion...")
+        memories_after = await client.list_memories(user_id=user_id)
+        print(f"   Remaining memories: {len(memories_after.data)}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

cookbook/agent_os/client/04_session_management.py

@@ -0,0 +1,97 @@
+"""
+Session Management with AgentOSClient
+
+This example demonstrates how to manage sessions using AgentOSClient.
+
+Prerequisites:
+1. Start an AgentOS server with an agent
+2. Run this script: python 04_session_management.py
+"""
+
+import asyncio
+
+from agno.os.client import AgentOSClient
+
+
+async def main():
+    async with AgentOSClient(base_url="http://localhost:7777") as client:
+        # Get available agents
+        config = await client.get_config()
+        if not config.agents:
+            print("No agents available")
+            return
+
+        agent_id = config.agents[0].id
+        user_id = "example-user"
+
+        print("=" * 60)
+        print("Session Management")
+        print("=" * 60)
+
+        # Create a session
+        print("\n1. Creating a session...")
+        session = await client.create_session(
+            agent_id=agent_id,
+            user_id=user_id,
+            session_name="My Test Session",
+        )
+        print(f"   Session ID: {session.session_id}")
+        print(f"   Session Name: {session.session_name}")
+
+        # List sessions
+        print("\n2. Listing sessions...")
+        sessions = await client.list_sessions(user_id=user_id)
+        print(f"   Found {len(sessions.data)} sessions")
+        for sess in sessions.data[:5]:  # Show first 5
+            print(f"   - {sess.session_id}: {sess.session_name or 'Unnamed'}")
+
+        # Get session details
+        print(f"\n3. Getting session {session.session_id}...")
+        details = await client.get_session(session.session_id)
+        print(f"   Agent ID: {details.agent_id}")
+        print(f"   User ID: {details.user_id}")
+        print(
+            f"   Runs: {len(details.runs) if hasattr(details, 'runs') and details.runs else 0}"
+        )
+
+        # Run some messages in the session
+        print("\n4. Running messages in session...")
+        await client.run_agent(
+            agent_id=agent_id,
+            message="Hello!",
+            session_id=session.session_id,
+        )
+        await client.run_agent(
+            agent_id=agent_id,
+            message="How are you?",
+            session_id=session.session_id,
+        )
+
+        # Get session runs
+        print("\n5. Getting session runs...")
+        runs = await client.get_session_runs(session_id=session.session_id)
+        print(f"   Found {len(runs)} runs in session")
+        for run in runs:
+            content_preview = (
+                (run.content[:50] + "...")
+                if run.content and len(str(run.content)) > 50
+                else run.content
+            )
+            print(f"   - {run.run_id}: {content_preview}")
+
+        # Rename session
+        print("\n6. Renaming session...")
+        renamed = await client.rename_session(
+            session_id=session.session_id,
+            session_name="Renamed Test Session",
+        )
+        print(f"   New name: {renamed.session_name}")
+
+        # Delete session
+        print(f"\n7. Deleting session {session.session_id}...")
+        await client.delete_session(session.session_id)
+        print("   Session deleted")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())