From 28186cad6697dd6f953caf8a6e9140d9320e33b3 Mon Sep 17 00:00:00 2001 From: Jenna Winkler <135358348+jenna-winkler@users.noreply.github.com> Date: Thu, 11 Dec 2025 10:27:10 -0500 Subject: [PATCH 1/5] Revise README for Agent Stack Server SDK Updated README to provide a comprehensive overview of the Agent Stack Server SDK, including installation instructions, key features, and usage examples. Signed-off-by: Jenna Winkler <135358348+jenna-winkler@users.noreply.github.com> --- apps/agentstack-sdk-py/README.md | 143 +++++++++++++++++++++++-------- 1 file changed, 109 insertions(+), 34 deletions(-) diff --git a/apps/agentstack-sdk-py/README.md b/apps/agentstack-sdk-py/README.md index afbf0ccac..252314962 100644 --- a/apps/agentstack-sdk-py/README.md +++ b/apps/agentstack-sdk-py/README.md @@ -1,45 +1,120 @@ -# Agent Stack SDK +# Agent Stack Server SDK -## Examples +Python SDK for deploying agents to Agent Stack infrastructure. -The examples connect to the Agent Stack for LLM inteference. +[![PyPI version](https://img.shields.io/pypi/v/agentstack-sdk.svg?style=plastic)](https://pypi.org/project/agentstack-sdk/) +[![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg?style=plastic)](https://opensource.org/licenses/Apache-2.0) +[![LF AI & Data](https://img.shields.io/badge/LF%20AI%20%26%20Data-0072C6?style=plastic&logo=linuxfoundation&logoColor=white)](https://lfaidata.foundation/projects/) -Run using: +## Overview + +The `agentstack-sdk` provides Python utilities for wrapping agents built with any framework (LangChain, CrewAI, BeeAI Framework, etc.) for deployment on Agent Stack. It handles the A2A (Agent-to-Agent) protocol implementation, platform service integration, and runtime requirements so you can focus on agent logic. + +## Key Features + +- **Framework-Agnostic Deployment** - Wrap agents from any framework for Agent Stack deployment +- **A2A Protocol Support** - Automatic handling of Agent-to-Agent communication +- **Platform Service Integration** - Connect to Agent Stack's managed LLM, embedding, file storage, and vector store services +- **Agent Wrapper** - Opinionated utilities with `yield` semantics and autowired services +- **Context Storage** - Manage data associated with conversation contexts + +## Installation ```bash -uv run examples/agent.py +uv add agentstack-sdk ``` -Connect to the agent using the CLI: +## Quickstart + +```python +import os +from a2a.types import AgentSkill, Message +from agentstack_sdk.server import Server +from agentstack_sdk.server.context import RunContext +from agentstack_sdk.server.store.platform_context_store import PlatformContextStore + +# Initialize server +server = Server() + +# Define your agent +@server.agent( + name="My Agent", + skills=[ + AgentSkill( + id="my-agent-skill", + name="My Agent", + description="Agent description here", + tags=["Chat"], + examples=["Example query 1", "Example query 2"] + ) + ], +) +async def my_agent( + input: Message, + context: RunContext, +): + """Your agent logic here""" + + # Store incoming message + await context.store(input) + + # Extract user message + user_msg = "".join( + part.root.text for part in input.parts + if part.root.kind == "text" + ) + + # Process and yield response + response_text = f"You said: {user_msg}" + yield response_text + + # Store response in context + from agentstack_sdk.a2a.types import AgentMessage + await context.store(AgentMessage(text=response_text)) + +# Run the server +if __name__ == "__main__": + server.run( + host=os.getenv("HOST", "127.0.0.1"), + port=int(os.getenv("PORT", 8000)), + context_store=PlatformContextStore() + ) +``` + +Run the agent: ```bash -uv run examples/cli.py +python my_agent.py ``` -## Plan - -- `agentstack_sdk` - - `a2a`: - - `extensions`: Shared definitions for A2A extensions - - `services`: Dependency injection extensions for external services - - `llm` - - `embedding` - - `docling` - - `file_store` - - `vector_store` - - `ui`: User interface extensions for Agent Stack UI - - `trajectory` - - `citations` - - `history`: store and allow requesting the full history of the context - - `server` - - `context_storage`: store data associated with context_id - - `wrapper`: conveniently build A2A agents -- opinionated on how tasks work, `yield`-semantics, autowired - services - - `services`: clients for external services - - `llm`: OpenAI-compatible chat LLM - - `embedding`: OpenAI-compatible embedding - - `text_extraction`: Docling-compatible text extraction - - `file_store`: S3-compatible file storage - - `vector_store`: some vector store? - - `client` - - ? +## Available Extensions + +The SDK includes extension support for: + +- **Citations** - Source attribution (`CitationExtensionServer`, `CitationExtensionSpec`) +- **Trajectory** - Agent decision logging (`TrajectoryExtensionServer`, `TrajectoryExtensionSpec`) +- **Settings** - User-configurable agent parameters (`SettingsExtensionServer`, `SettingsExtensionSpec`) +- **LLM Services** - Platform-managed language models (`LLMServiceExtensionServer`, `LLMServiceExtensionSpec`) +- **Agent Details** - Metadata and UI enhancements (`AgentDetail`) +- **And more** - See [Documentation](https://agentstack.beeai.dev/stable/agent-development/overview). + +Each extension provides both server-side handlers and A2A protocol specifications for seamless integration with Agent Stack's UI and infrastructure. + +## Resources + +- [Agent Stack Documentation](https://agentstack.beeai.dev) +- [GitHub Repository](https://github.com/i-am-bee/agentstack) +- [PyPI Package](https://pypi.org/project/agentstack-sdk/) + +## Contributing + +Contributions are welcome! Please see the [Contributing Guide](https://github.com/i-am-bee/agentstack/blob/main/CONTRIBUTING.md) for details. + +## Support + +- [GitHub Issues](https://github.com/i-am-bee/agentstack/issues) +- [GitHub Discussions](https://github.com/i-am-bee/agentstack/discussions) + +--- + +Developed by contributors to the BeeAI project, this initiative is part of the [Linux Foundation AI & Data program](https://lfaidata.foundation/projects/). Its development follows open, collaborative, and community-driven practices. From cf345a4684e6b9647fe47b674f610fdf9012bab1 Mon Sep 17 00:00:00 2001 From: Jenna Winkler <135358348+jenna-winkler@users.noreply.github.com> Date: Thu, 11 Dec 2025 10:30:19 -0500 Subject: [PATCH 2/5] Update README to remove 'Agent Wrapper' section Removed the 'Agent Wrapper' feature from the README. Signed-off-by: Jenna Winkler <135358348+jenna-winkler@users.noreply.github.com> --- apps/agentstack-sdk-py/README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/apps/agentstack-sdk-py/README.md b/apps/agentstack-sdk-py/README.md index 252314962..1bc70d7ca 100644 --- a/apps/agentstack-sdk-py/README.md +++ b/apps/agentstack-sdk-py/README.md @@ -15,7 +15,6 @@ The `agentstack-sdk` provides Python utilities for wrapping agents built with an - **Framework-Agnostic Deployment** - Wrap agents from any framework for Agent Stack deployment - **A2A Protocol Support** - Automatic handling of Agent-to-Agent communication - **Platform Service Integration** - Connect to Agent Stack's managed LLM, embedding, file storage, and vector store services -- **Agent Wrapper** - Opinionated utilities with `yield` semantics and autowired services - **Context Storage** - Manage data associated with conversation contexts ## Installation From 8db6d7df596856f577f2782c1790a3ebfcaddbd5 Mon Sep 17 00:00:00 2001 From: Jenna Winkler <135358348+jenna-winkler@users.noreply.github.com> Date: Thu, 11 Dec 2025 10:34:32 -0500 Subject: [PATCH 3/5] Update agent example and quickstart instructions Refactor README to update agent definition and usage examples. Signed-off-by: Jenna Winkler <135358348+jenna-winkler@users.noreply.github.com> --- apps/agentstack-sdk-py/README.md | 67 ++++++++++---------------------- 1 file changed, 21 insertions(+), 46 deletions(-) diff --git a/apps/agentstack-sdk-py/README.md b/apps/agentstack-sdk-py/README.md index 1bc70d7ca..da897e984 100644 --- a/apps/agentstack-sdk-py/README.md +++ b/apps/agentstack-sdk-py/README.md @@ -27,63 +27,38 @@ uv add agentstack-sdk ```python import os -from a2a.types import AgentSkill, Message + +from a2a.types import ( + Message, +) +from a2a.utils.message import get_message_text from agentstack_sdk.server import Server from agentstack_sdk.server.context import RunContext -from agentstack_sdk.server.store.platform_context_store import PlatformContextStore +from agentstack_sdk.a2a.types import AgentMessage -# Initialize server server = Server() -# Define your agent -@server.agent( - name="My Agent", - skills=[ - AgentSkill( - id="my-agent-skill", - name="My Agent", - description="Agent description here", - tags=["Chat"], - examples=["Example query 1", "Example query 2"] - ) - ], -) -async def my_agent( - input: Message, - context: RunContext, -): - """Your agent logic here""" - - # Store incoming message - await context.store(input) - - # Extract user message - user_msg = "".join( - part.root.text for part in input.parts - if part.root.kind == "text" - ) - - # Process and yield response - response_text = f"You said: {user_msg}" - yield response_text - - # Store response in context - from agentstack_sdk.a2a.types import AgentMessage - await context.store(AgentMessage(text=response_text)) - -# Run the server +@server.agent() +async def example_agent(input: Message, context: RunContext): + """Polite agent that greets the user""" + hello_template: str = os.getenv("HELLO_TEMPLATE", "Ciao %s!") + yield AgentMessage(text=hello_template % get_message_text(input)) + +def run(): + try: + server.run(host=os.getenv("HOST", "127.0.0.1"), port=int(os.getenv("PORT", 8000))) + except KeyboardInterrupt: + pass + + if __name__ == "__main__": - server.run( - host=os.getenv("HOST", "127.0.0.1"), - port=int(os.getenv("PORT", 8000)), - context_store=PlatformContextStore() - ) + run() ``` Run the agent: ```bash -python my_agent.py +uv run my_agent.py ``` ## Available Extensions From 2c283ebe913adad58eab00a914445d70276b6e85 Mon Sep 17 00:00:00 2001 From: Jenna Winkler <135358348+jenna-winkler@users.noreply.github.com> Date: Thu, 11 Dec 2025 10:35:16 -0500 Subject: [PATCH 4/5] Fix formatting in README.md for extensions list Signed-off-by: Jenna Winkler <135358348+jenna-winkler@users.noreply.github.com> --- apps/agentstack-sdk-py/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apps/agentstack-sdk-py/README.md b/apps/agentstack-sdk-py/README.md index da897e984..0c348b336 100644 --- a/apps/agentstack-sdk-py/README.md +++ b/apps/agentstack-sdk-py/README.md @@ -70,7 +70,7 @@ The SDK includes extension support for: - **Settings** - User-configurable agent parameters (`SettingsExtensionServer`, `SettingsExtensionSpec`) - **LLM Services** - Platform-managed language models (`LLMServiceExtensionServer`, `LLMServiceExtensionSpec`) - **Agent Details** - Metadata and UI enhancements (`AgentDetail`) -- **And more** - See [Documentation](https://agentstack.beeai.dev/stable/agent-development/overview). +- **And more** - See [Documentation](https://agentstack.beeai.dev/stable/agent-development/overview) Each extension provides both server-side handlers and A2A protocol specifications for seamless integration with Agent Stack's UI and infrastructure. From 80e82d1d330b0195277c61b27cddff3ea0b91ed2 Mon Sep 17 00:00:00 2001 From: Jenna Winkler <135358348+jenna-winkler@users.noreply.github.com> Date: Thu, 11 Dec 2025 10:39:34 -0500 Subject: [PATCH 5/5] Update README to clarify SDK purpose Signed-off-by: Jenna Winkler <135358348+jenna-winkler@users.noreply.github.com> --- apps/agentstack-sdk-py/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apps/agentstack-sdk-py/README.md b/apps/agentstack-sdk-py/README.md index 0c348b336..fe936df40 100644 --- a/apps/agentstack-sdk-py/README.md +++ b/apps/agentstack-sdk-py/README.md @@ -1,6 +1,6 @@ # Agent Stack Server SDK -Python SDK for deploying agents to Agent Stack infrastructure. +Python SDK for packaging agents for deployment to Agent Stack infrastructure. [![PyPI version](https://img.shields.io/pypi/v/agentstack-sdk.svg?style=plastic)](https://pypi.org/project/agentstack-sdk/) [![License](https://img.shields.io/badge/License-Apache_2.0-blue.svg?style=plastic)](https://opensource.org/licenses/Apache-2.0)