diff --git a/docs/deploy/deploy-your-agents.mdx b/docs/deploy/deploy-your-agents.mdx index 390b62262..172006657 100644 --- a/docs/deploy/deploy-your-agents.mdx +++ b/docs/deploy/deploy-your-agents.mdx @@ -8,7 +8,7 @@ Once you've wrapped your agent with the Agent Stack server, you need to containe ## Prerequisites - Docker installed and running (or use GitHub Actions via template) -- Agent wrapped with Agent Stack SDK ([Wrap Existing Agents](/deploy/wrap-existing-agent) or [Build New Agent](/deploy/build-new-agent)) +- Agent wrapped with Agent Stack SDK ([Wrap Existing Agents](/deploy/wrap-existing-agents) or [Build New Agent](/introduction/start-building-agents)) - Agent Stack installed ([Quickstart](/introduction/quickstart)) ## Containerize Your Agent @@ -142,7 +142,7 @@ agentstack build . --dockerfile=./deploy/Containerfile --import Now that your agent is deployed, enhance it with extensions: - + Change your agent's LLM at runtime and manage model connections dynamically diff --git a/docs/extensions/agent-settings.mdx b/docs/extensions/agent-settings.mdx index 91e5cb0c4..2addeaaa3 100644 --- a/docs/extensions/agent-settings.mdx +++ b/docs/extensions/agent-settings.mdx @@ -8,7 +8,7 @@ Sometimes you need to give users control over how your agent behaves during a co The Agent Stack platform provides a Settings extension that creates an interactive UI component where users can configure these options before or during their interaction with your agent. -Settings extensions are a type of [Platform Extension](/concepts/extensions) that allows you to easily "inject dependencies" into your agent. This follows the inversion of control principle where your agent defines what it needs, and the platform provides those dependencies. +Settings extensions are a type of [Service Extension](/sdk/overview#dependency-injection-service-extensions) that allows you to easily "inject dependencies" into your agent. This follows the inversion of control principle where your agent defines what it needs, and the platform provides those dependencies. ## Quickstart diff --git a/docs/extensions/overview.mdx b/docs/extensions/overview.mdx deleted file mode 100644 index a12645e1e..000000000 --- a/docs/extensions/overview.mdx +++ /dev/null @@ -1,118 +0,0 @@ ---- -title: Extensions Overview ---- - -Platform extensions enable agents to access external services and UI components through dependency injection. They provide automatic configuration, portable agent code, user-configured services with authentication, and remain entirely optional. - -## Extension Types - -### Service Extensions - -Service extensions provide configured access to external services: - -- **LLM Service**: Language model access (OpenAI, Ollama, IBM Granite, and more) -- **Embedding Service**: Text embedding generation for RAG and semantic search -- **Platform API**: File storage, vector databases, and other platform services -- **MCP**: Model Context Protocol integration - -### UI Extensions - -UI extensions add rich interactive components to the user interface: - -- **Trajectory**: Visualize agent reasoning with step-by-step execution traces -- **Citation**: Display source references with clickable inline links -- **Form**: Collect structured user input through interactive forms -- **Settings**: Let users configure agent behavior and preferences - -### Authentication Extensions - -Authentication extensions handle secure access to protected resources: -- **OAuth**: Standardized OAuth-based authentication and token management -- **Secrets**: Secure storage and retrieval of API keys and credentials - -## Using Extensions with Dependency Injection - -Extensions are injected into agent functions using `Annotated` type hints: - -```python -from typing import Annotated -from agentstack_sdk.a2a.extensions import LLMServiceExtensionServer, LLMServiceExtensionSpec - -async def my_agent( - input: Message, - context: RunContext, - llm: Annotated[LLMServiceExtensionServer, LLMServiceExtensionSpec.single_demand()] -): - # Platform provides configured LLM access - pass -``` - -## Checking Extension Availability - -Extensions are optional by design. Always verify an extension is provided before using it: - -```python -if llm: - # Use LLM functionality - pass -else: - # Provide fallback or inform user - yield "LLM not configured" -``` - -## Suggesting Preferred Models - -Service extensions accept model suggestions in priority order. The platform selects the first available model: - -```python -LLMServiceExtensionSpec.single_demand( - suggested=("openai/gpt-4o", "ollama/llama3.1", "ibm/granite-3-8b") -) -``` - -## Extension Reference - -### OAuth Extension - -Enables OAuth-based authentication for secure access to protected resources on behalf of users. Particularly useful for MCP clients that need user identity for third-party tools. - -- **Example:** [agentstack-sdk-py/examples/oauth.py](https://github.com/i-am-bee/agentstack/blob/main/apps/agentstack-sdk-py/examples/oauth.py) - -### Secrets Extension - -Provides secure storage and retrieval of sensitive data like API keys and tokens. Secrets can be requested before conversation start or dynamically during runtime. - -- **Example:** [agentstack-sdk-py/examples/secrets_agent.py](https://github.com/i-am-bee/agentstack/blob/main/apps/agentstack-sdk-py/examples/secrets_agent.py) -- **Documentation:** [Secrets Guide](/build-agents/secrets) - -### Citation Extension - -Renders inline citation icons with source information, optionally marking text ranges. Makes agent responses more transparent and verifiable. - -- **Documentation:** [Citations Guide](/build-agents/citations) - -### Trajectory Extension - -Tracks and visualizes agent reasoning steps and tool execution. Provides transparency into the agent's decision-making process. - -- **Documentation:** [Trajectory Guide](/build-agents/trajectory) - -### Form Extension - -Collects structured data through interactive forms with fields like text inputs, dropdowns, date pickers, file uploads, and checkboxes. Forms can be presented initially or requested dynamically during conversations. - -- **Example:** [agentstack-sdk-py/examples/request_form_agent.py](https://github.com/i-am-bee/agentstack/blob/main/apps/agentstack-sdk-py/examples/request_form_agent.py) -- **Documentation:** [Forms Guide](/build-agents/forms) - -### Settings Extension - -Gives users control over agent behavior through configurable parameters like thinking mode, response style, and other agent-specific options. - -- **Example:** [agentstack-sdk-py/examples/settings_agent.py](https://github.com/i-am-bee/agentstack/blob/main/apps/agentstack-sdk-py/examples/settings_agent.py) -- **Documentation:** [Agent Settings Guide](/build-agents/agent-settings) - ---- - -## Key Benefits - -Extensions make agents adaptable across deployment environments while providing rich, interactive user experiences. The dependency injection pattern ensures agents remain portable and testable, while optional extension checking enables graceful degradation when services aren't available. diff --git a/docs/extensions/rag.mdx b/docs/extensions/rag.mdx index 444952856..4556c41bc 100644 --- a/docs/extensions/rag.mdx +++ b/docs/extensions/rag.mdx @@ -342,6 +342,6 @@ async def rag_agent( ### Next steps To further improve the agent, learn how to use other parts of the platform such as LLMs, file uploads and conversations: -- [LLM extension](./llm-configuration) -- [Multi-turn conversations](./multi-turn) -- [File handling](./file-handling) +- [LLM extension](/extensions/llm-proxy-service) +- [Multi-turn conversations](/guides/multi-turn) +- [File handling](/guides/files) diff --git a/docs/introduction/connect-a2a-agents.mdx b/docs/introduction/connect-a2a-agents.mdx index fdd46dbd3..01b8446b4 100644 --- a/docs/introduction/connect-a2a-agents.mdx +++ b/docs/introduction/connect-a2a-agents.mdx @@ -32,7 +32,7 @@ That's it! Your agent is now registered with Agent Stack and accessible through The proxy creates a bridge between your A2A agent and Agent Stack by: 1. **Intercepting agent card requests** - Captures `/.well-known/agent-card.json` requests from any A2A client -2. **Adding Agent Details extension** - Automatically injects the necessary [AgentDetail](/build-agents/agent-details) extension data that enables the agent to work within the Agent Stack ecosystem +2. **Adding Agent Details extension** - Automatically injects the necessary [AgentDetail](/extensions/agent-details) extension data that enables the agent to work within the Agent Stack ecosystem 3. **Auto-registration** - Automatically registers the modified agent with the Agent Stack, making it immediately available