### Run Reference Example

Source: https://github.com/i-am-bee/agentstack/blob/main/docs/stable/custom-ui/architecture-guide.mdx

Steps to set up and run the reference chat UI example, including environment variable configuration and installation.

```bash
cd apps/agentstack-sdk-ts/examples/chat-ui
cp .env.example .env
pnpm install
pnpm dev
```

--------------------------------

### Quickstart: Build and Interact with an Agent

Source: https://github.com/i-am-bee/agentstack/blob/main/apps/agentstack-sdk-ts/README.md

This example demonstrates how to initialize the SDK, authenticate, create a context, and send a message to an agent. It also shows how to handle various task status updates and stream responses.

```typescript
import {
  buildApiClient,
  createAuthenticatedFetch,
  unwrapResult,
  getAgentCardPath,
  handleAgentCard,
  handleTaskStatusUpdate,
  resolveUserMetadata,
  type TaskStatusUpdateType,
  type Fulfillments,
} from 'agentstack-sdk';
import {
  ClientFactory,
  ClientFactoryOptions,
  DefaultAgentCardResolver,
  JsonRpcTransportFactory,
} from '@a2a-js/sdk/client';

const baseUrl = 'https://your-agentstack-instance.com'; // or http://localhost:8333 for local development
const accessToken = '<user-access-token>';

const api = buildApiClient({
  baseUrl,
  fetch: createAuthenticatedFetch(accessToken),
});

const providers = unwrapResult(await api.listProviders());
const providerId = providers[0]?.id;

const context = unwrapResult(await api.createContext({ provider_id: providerId }));
const contextToken = unwrapResult(
  await api.createContextToken({
    context_id: context.id,
    grant_global_permissions: {
      llm: ['*'],
      embeddings: ['*'],
      a2a_proxy: ['*'],
    },
    grant_context_permissions: {
      files: ['*'],
      vector_stores: ['*'],
      context_data: ['*'],
    },
  }),
);

const fetchImpl = createAuthenticatedFetch(contextToken.token);
const factory = new ClientFactory(
  ClientFactoryOptions.createFrom(ClientFactoryOptions.default, {
    transports: [new JsonRpcTransportFactory({ fetchImpl })],
    cardResolver: new DefaultAgentCardResolver({ fetchImpl }),
  }),
);

const agentCardPath = getAgentCardPath(providerId);
const client = await factory.createFromUrl(baseUrl, agentCardPath);

const card = await client.getAgentCard();
const { resolveMetadata, demands } = handleAgentCard(card);

const selectedLlmModels: Record<string, string> = { default: 'gpt-4o' };

const fulfillments: Fulfillments = {
  llm: demands.llmDemands
    ? async ({ llm_demands }) => ({
        llm_fulfillments: Object.fromEntries(
          Object.keys(llm_demands).map((key) => [
            key,
            {
              identifier: 'llm_proxy',
              api_base: `${baseUrl}/api/v1/openai/`,
              api_key: contextToken.token,
              api_model: selectedLlmModels[key],
            },
          ]),
        ),
      })
    : undefined,
};

const agentMetadata = await resolveMetadata(fulfillments);

const stream = client.sendMessageStream({
  message: {
    kind: 'message',
    role: 'user',
    messageId: crypto.randomUUID(),
    contextId: context.id,
    parts: [{ kind: 'text', text: 'Hello' }],
    metadata: agentMetadata,
  },
});

let taskId: string | undefined;

for await (const event of stream) {
  switch (event.kind) {
    case 'task':
      taskId = event.id;
    case 'status-update':
      taskId = event.taskId;

      for (const update of handleTaskStatusUpdate(event)) {
        switch (update.type) {
          case TaskStatusUpdateType.FormRequired:
          // Render form
          case TaskStatusUpdateType.OAuthRequired:
          // Redirect to update.url
          case TaskStatusUpdateType.SecretRequired:
          // Prompt for secrets
          case TaskStatusUpdateType.ApprovalRequired:
          // Request approval
          case TaskStatusUpdateType.TextInputRequired:
          // Prompt for text input
        }
      }
    case 'message':
    // Render message parts and metadata
    case 'artifact-update':
    // Render artifacts
  }
}

```

--------------------------------

### Sync Examples with Docs

Source: https://github.com/i-am-bee/agentstack/blob/main/CONTRIBUTING.md

After editing an example agent, run this command to sync the changes to the documentation. This is necessary for examples embedded using embedme tags.

```bash
mise run docs:fix
```

--------------------------------

### Start Local Development Environment

Source: https://github.com/i-am-bee/agentstack/blob/main/CONTRIBUTING.md

Starts the local development environment, including Telepresence setup. Requires root access for networking stack configuration. This command replaces the agentstack in the cluster and forwards traffic to localhost.

```sh
mise run agentstack-server:dev:start
```

--------------------------------

### Scaffold Example: Basic History

Source: https://github.com/i-am-bee/agentstack/blob/main/examples/README.md

An example of using the `example:create` command to scaffold a new agent example for basic history functionality.

```bash
mise run example:create agent-integration/multi-turn/basic-history "Example demonstrating basic history."
```

--------------------------------

### Create New Example with Mise

Source: https://github.com/i-am-bee/agentstack/blob/main/CONTRIBUTING.md

Use this command to scaffold a new example agent and its corresponding e2e test. Ensure you provide the path and a description for the new example.

```bash
mise run example:create <path> <description>
```

--------------------------------

### Deploy AgentStack Starter Example

Source: https://github.com/i-am-bee/agentstack/blob/main/docs/stable/deploy-agents/deploy-your-agents.mdx

Deploy the agentstack-starter example agent without any modifications by issuing this command.

```bash
agentstack add https://github.com/i-am-bee/agentstack-starter
```

--------------------------------

### Setup Agentstack Models

Source: https://github.com/i-am-bee/agentstack/blob/main/helm/templates/NOTES.txt

This command initiates the setup process for Agentstack models.

```bash
# Setup models
  agentstack model setup
```

--------------------------------

### Install Mise and Project Dependencies

Source: https://github.com/i-am-bee/agentstack/blob/main/CONTRIBUTING.md

Install Mise using Homebrew and then use Mise to install project-specific tools and dependencies.

```sh
brew install mise # more ways to install: https://mise.jdx.dev/installing-mise.html
mise trust
mise install
```

--------------------------------

### Python: Initialize RequirementAgent with Tools and Middlewares

Source: https://github.com/i-am-bee/agentstack/blob/main/apps/beeai-web/src/modules/blog/posts/reliable-ai-agents.mdx

This snippet demonstrates the basic setup for a RequirementAgent in Python. It includes importing necessary components like RequirementAgent, ConditionalRequirement, various tools (Search, Think, Weather), ChatModel, and GlobalTrajectoryMiddleware. Ensure 'beeai_framework' is installed.

```python
# uv add beeai_framework
from beeai_framework.agents.requirement import RequirementAgent
from beeai_framework.agents.requirement.requirements.conditional import ConditionalRequirement
from beeai_framework.tools.search.duckduckgo import DuckDuckGoSearchTool
from beeai_framework.tools.think import ThinkTool
from beeai_framework.tools.weather import OpenMeteoTool
from beeai_framework.backend import ChatModel
from beeai_framework.middleware.trajectory import GlobalTrajectoryMiddleware
import asyncio

```

--------------------------------

### Install uv via Winget (Windows)

Source: https://github.com/i-am-bee/agentstack/blob/main/docs/stable/introduction/quickstart.mdx

Install uv on Windows using the Winget package manager. Remember to close and reopen your terminal after installation.

```bash
winget install astral-sh.uv
```

```bash
uv tool update-shell
```

--------------------------------

### Complete Workflow Example

Source: https://github.com/i-am-bee/agentstack/blob/main/docs/stable/experimental/connectors.mdx

A comprehensive example demonstrating the full lifecycle of a connector: creation, connection, usage, disconnection, and deletion.

```python
import asyncio
from agentstack_sdk.platform import Connector, ConnectorState

async def main():
    # Create connector
    connector = await Connector.create(url="https://mcp.stripe.com")
    
    # Connect (browser opens for OAuth if needed)
    connector = await connector.connect()
    connector = await connector.wait_for_state(state=ConnectorState.connected)
    
    # Use the connector
    for k, v in connector.model_dump().items():
        print(f"{k}: {v}")
    
    # Cleanup
    await connector.disconnect()
    await connector.delete()
    await connector.wait_for_deletion()

asyncio.run(main())
```

--------------------------------

### Start Platform Using Configuration File

Source: https://github.com/i-am-bee/agentstack/blob/main/CONTRIBUTING.md

Start the local platform using a specified configuration file, which can include settings for authentication and user seeding.

```sh
mise run agentstack:start -f config.yaml
```

--------------------------------

### Start Your Agent and Test It

Source: https://github.com/i-am-bee/agentstack/blob/main/README.md

Clone the starter project, navigate into the directory, and start the agent server. Then, in a separate terminal, run a test command to interact with your agent.

```sh
git clone https://github.com/i-am-bee/agentstack-starter my-agent
cd my-agent
uv run server               # Start your agent
```

```sh
agentstack run example_agent "Alice"  # Test your agent
```

--------------------------------

### Enable Phoenix Observability

Source: https://github.com/i-am-bee/agentstack/blob/main/docs/stable/agent-integration/observability.mdx

Install and start Phoenix to enable observability. This command updates the configuration without data loss.

```bash
agentstack platform start --set phoenix.enabled=true
```

--------------------------------

### Install uv via Scoop (Windows)

Source: https://github.com/i-am-bee/agentstack/blob/main/docs/stable/introduction/quickstart.mdx

Install uv on Windows using the Scoop package manager. Remember to close and reopen your terminal after installation.

```bash
scoop install uv
```

```bash
uv tool update-shell
```

--------------------------------

### Start Platform with Langfuse Configuration

Source: https://github.com/i-am-bee/agentstack/blob/main/docs/stable/agent-integration/observability.mdx

Start the Agent Stack platform using a custom configuration file for Langfuse observability.

```bash
agentstack platform start -f config.yaml
```

--------------------------------

### Start Platform with OIDC Authentication Enabled

Source: https://github.com/i-am-bee/agentstack/blob/main/CONTRIBUTING.md

Start the local platform with OAuth/OIDC authentication enabled. This will set up Keycloak, which requires further configuration for users and roles.

```bash
mise agentstack:start --set auth.enabled=true
```

--------------------------------

### Install Agent Stack CLI (Linux/macOS Manual)

Source: https://github.com/i-am-bee/agentstack/blob/main/docs/stable/introduction/quickstart.mdx

Manually install the Agent Stack CLI using uv. This command installs uv, the agentstack-cli, and sets up the Python environment.

```bash
uv python install --quiet --python-preference=only-managed --no-bin 3.14 && uv tool install --refresh --force --python-preference=only-managed --python=3.14 agentstack-cli && agentstack self install
```

--------------------------------

### Start Local Platform with Custom Settings

Source: https://github.com/i-am-bee/agentstack/blob/main/CONTRIBUTING.md

Start the local platform with custom configurations applied. Use '--set' to override specific settings, such as enabling features like docling or OIDC.

```sh
mise agentstack:start --set docling.enabled=true --set oidc.enabled=true 
```

--------------------------------

### Install Mintlify CLI

Source: https://github.com/i-am-bee/agentstack/blob/main/docs/stable/README.md

Install the Mintlify CLI globally to preview documentation changes locally. This command is run in your terminal.

```bash
npm i -g mintlify
```

--------------------------------

### agentstack model setup

Source: https://github.com/i-am-bee/agentstack/blob/main/docs/stable/reference/cli-reference.mdx

Interactive setup for LLM and embedding provider environment variables [Admin only]

```APIDOC
### `agentstack model setup`

Interactive setup for LLM and embedding provider environment variables [Admin only]

**Usage**:

```console
$ agentstack model setup [OPTIONS]
```

**Options**:

* `-v, --verbose`: Show verbose output
* `--llm-provider TEXT`: LLM provider type (e.g. openai, anthropic, watsonx)
* `--llm-api-key TEXT`: LLM provider API key
* `--llm-base-url TEXT`: Base URL for &#x27;other&#x27; LLM provider
* `--llm-watsonx-region TEXT`: IBM watsonx region for LLM (e.g. us-south)
* `--llm-watsonx-project-or-space TEXT`: IBM watsonx: &#x27;project&#x27; or &#x27;space&#x27;
* `--llm-watsonx-project-or-space-id TEXT`: IBM watsonx project or space ID for LLM
* `--llm-model TEXT`: Default LLM model ID (e.g. openai:gpt-4o)
* `--llm-bedrock-region TEXT`: AWS region for Bedrock LLM (e.g. us-east-1)
* `--llm-bedrock-access-key TEXT`: AWS Access Key ID for Bedrock LLM
* `--llm-bedrock-secret-key TEXT`: AWS Secret Access Key for Bedrock LLM
* `--embedding-provider TEXT`: Embedding provider type (e.g. openai, watsonx)
* `--embedding-api-key TEXT`: Embedding provider API key
* `--embedding-base-url TEXT`: Base URL for &#x27;other&#x27; embedding provider
* `--embedding-watsonx-region TEXT`: IBM watsonx region for embedding
* `--embedding-watsonx-project-or-space TEXT`: IBM watsonx: &#x27;project&#x27; or &#x27;space&#x27;
* `--embedding-watsonx-project-or-space-id TEXT`: IBM watsonx project or space ID for embedding
* `--embedding-model TEXT`: Default embedding model ID
* `--embedding-bedrock-region TEXT`: AWS region for Bedrock embedding (e.g. us-east-1)
* `--embedding-bedrock-access-key TEXT`: AWS Access Key ID for Bedrock embedding
* `--embedding-bedrock-secret-key TEXT`: AWS Secret Access Key for Bedrock embedding
* `--skip-embedding`: Skip embedding provider setup
* `-y, --yes`: Skip confirmation prompts and auto-select recommended models
* `--help`: Show this message and exit.
```

--------------------------------

### Install uv via Chocolatey (Windows)

Source: https://github.com/i-am-bee/agentstack/blob/main/docs/stable/introduction/quickstart.mdx

Install uv on Windows using the Chocolatey package manager. Remember to close and reopen your terminal after installation.

```bash
choco install uv
```

```bash
uv tool update-shell
```

--------------------------------

### Run Example E2E Tests

Source: https://github.com/i-am-bee/agentstack/blob/main/CONTRIBUTING.md

Execute only the end-to-end tests for examples using this command. These tests are separate from the core e2e suite and are crucial for verifying example functionality.

```bash
mise run agentstack-server:test:e2e-examples
```

--------------------------------

### Automate User and Role Setup for OIDC

Source: https://github.com/i-am-bee/agentstack/blob/main/CONTRIBUTING.md

Automate the setup of Keycloak users and roles by providing a configuration file. This is an alternative to manual setup through the Keycloak UI.

```yaml
auth:
  enabled: true
keycloak:
  auth:
    seedAgentstackUsers:
      - username: admin
        password: admin
        firstName: Admin
        lastName: User
        email: admin@beeai.dev
        roles: ["agentstack-admin"]
        enabled: true
```

--------------------------------

### Setup LLM and Login

Source: https://github.com/i-am-bee/agentstack/blob/main/docs/stable/deploy-agent-stack/deployment-guide.mdx

Configure your model provider and log in if authentication is enabled for the Agent Stack platform.

```shell
# agentstack server login (if auth is enabled)
agentstack model setup

```

--------------------------------

### Start Storybook for Keycloak Theme

Source: https://github.com/i-am-bee/agentstack/blob/main/apps/keycloak-theme/README.md

Run this command to start Storybook on port 6006. This allows for isolated development and testing of all theme pages.

```bash
mise run keycloak-theme:storybook
```

--------------------------------

### Install Agent Stack CLI (Windows Manual)

Source: https://github.com/i-am-bee/agentstack/blob/main/docs/stable/introduction/quickstart.mdx

Manually install the Agent Stack CLI on Windows using uv. This command installs uv, the agentstack-cli, and initiates the self-installation process.

```powershell
uv python install --quiet --python-preference=only-managed --no-bin 3.14; uv tool install --refresh --force --python-preference=only-managed --python=3.14 agentstack-cli; agentstack self install
```

--------------------------------

### Install Agent Stack CLI

Source: https://github.com/i-am-bee/agentstack/blob/main/apps/beeai-web/src/modules/blog/posts/introducing-agent-stack.mdx

Use this command to install the Agent Stack CLI for deploying and managing agents. It fetches and executes the installation script.

```bash
sh -c "$(curl -LsSf https://raw.githubusercontent.com/i-am-bee/agentstack/install/install.sh)"
```

--------------------------------

### Troubleshoot Platform Not Starting

Source: https://github.com/i-am-bee/agentstack/blob/main/docs/stable/deploy-agent-stack/deployment-guide.mdx

Diagnose issues with the platform not starting by checking pod status, server logs, init container logs, and Kubernetes events.

```bash
# Check pod status
kubectl get pod
```

```bash
# Check server logs
kubectl logs deployment/agentstack-server
# If server is not starting, check specific init container logs (e.g. migrations)
kubectl logs deployment/agentstack-server -c run-migrations
```

```bash
# Check events
kubectl get events --sort-by=.lastTimestamp
```

--------------------------------

### Start Agent Stack Platform

Source: https://github.com/i-am-bee/agentstack/blob/main/docs/stable/reference/cli-reference.mdx

Starts the Agent Stack platform. This command is intended for local use only.

```console
agentstack platform start
```

--------------------------------

### Complete Workflow Example

Source: https://github.com/i-am-bee/agentstack/blob/main/docs/stable/experimental/connectors.mdx

Demonstrates a complete workflow from creating a connector to connecting, using it, and finally cleaning up by disconnecting and deleting.

```APIDOC
## Complete Workflow Example

### Description
Illustrates a full cycle of connector management: creation, connection, usage, disconnection, and deletion.

### Request Example
```python
import asyncio
from agentstack_sdk.platform import Connector, ConnectorState

async def main():
    # Create connector
    connector = await Connector.create(url="https://mcp.stripe.com")
    
    # Connect (browser opens for OAuth if needed)
    connector = await connector.connect()
    connector = await connector.wait_for_state(state=ConnectorState.connected)
    
    # Use the connector
    for k, v in connector.model_dump().items():
        print(f"{k}: {v}")
    
    # Cleanup
    await connector.disconnect()
    await connector.delete()
    await connector.wait_for_deletion()

asyncio.run(main())
```
```

--------------------------------

### Run Your Agent

Source: https://github.com/i-am-bee/agentstack/blob/main/docs/stable/deploy-agents/building-agents.mdx

Execute your agent with a specified name and persona. This command starts an instance of your agent.

```bash
agentstack run example_agent "Alice"
```

--------------------------------

### Install BeeAI Framework with A2A Extras

Source: https://github.com/i-am-bee/agentstack/blob/main/apps/beeai-web/src/modules/blog/posts/a2a-server.mdx

Install the BeeAI Framework with A2A extras using uv. This command adds the necessary dependencies for A2A communication.

```bash
uv init
uv add 'beeai-framework[a2a]'
```

--------------------------------

### agentstack platform start

Source: https://github.com/i-am-bee/agentstack/blob/main/docs/stable/reference/cli-reference.mdx

Starts the Agent Stack platform. This command is intended for local use only.

```APIDOC
## `agentstack platform start`

Start Agent Stack platform. [Local only]

**Usage**:

```console
$ agentstack platform start [OPTIONS]
```

**Options**:

* `--set TEXT`: Set Helm chart values using <key>=<value> syntax  [default: <class 'list'>]
* `--image-pull-mode [guest|host|hybrid|skip]`: guest = pull all images inside VM 
host = pull unavailable images on host, then import all
hybrid = import available images from host, pull the rest in VM
skip = skip explicit pull step (Kubernetes will attempt to pull missing images)  [default: guest]
* `-f PATH`: Set Helm chart values using yaml values file
* `--lima-image TEXT`: Local path or URL to Lima image (.qcow2)
* `--wsl-image TEXT`: Local path or URL to WSL distro image (.wsl)
* `-v, --verbose`: Show verbose output
* `--help`: Show this message and exit.
```

--------------------------------

### agentstack platform start

Source: https://github.com/i-am-bee/agentstack/blob/main/docs/stable/reference/cli-reference.mdx

Starts the Agent Stack platform. This command is intended for local use only.

```APIDOC
## agentstack platform start

### Description
Start Agent Stack platform. [Local only]

### Usage
```console
$ agentstack platform start [OPTIONS]
```

### Options
* `--help` - Show this message and exit.
```

--------------------------------

### Install Agent Stack Prerequisites

Source: https://github.com/i-am-bee/agentstack/blob/main/docs/stable/reference/cli-reference.mdx

Installs the necessary prerequisites for the Agent Stack platform. Use the '-y' flag to skip confirmation prompts.

```console
agentstack self install
```

```console
agentstack self install -y
```

--------------------------------

### Install agentstack-sdk

Source: https://github.com/i-am-bee/agentstack/blob/main/apps/agentstack-sdk-py/README.md

Install the agentstack-sdk using uv. This command adds the SDK to your project's dependencies.

```bash
uv add agentstack-sdk
```

--------------------------------

### Start Agent Stack Platform

Source: https://github.com/i-am-bee/agentstack/blob/main/docs/stable/reference/cli-reference.mdx

Use this command to start the Agent Stack platform. It supports setting Helm chart values and configuring image pull modes. This command is local only.

```bash
agentstack platform start [OPTIONS]
```

--------------------------------

### Start Local Platform with Built Images

Source: https://github.com/i-am-bee/agentstack/blob/main/CONTRIBUTING.md

Build and import local Docker images for the agentstack server and UI, then start the platform. This command bypasses the use of published images.

```sh
mise agentstack:start
```

--------------------------------

### Advanced Server SDK Example with Form Request

Source: https://github.com/i-am-bee/agentstack/blob/main/docs/stable/agent-integration/overview.mdx

This example demonstrates an agent that pauses execution to request user input via a form. It utilizes UI extensions for form creation and handles user data submission.

```python
# Copyright 2025 © BeeAI a Series of LF Projects, LLC
# SPDX-License-Identifier: Apache-2.0

import os
from typing import Annotated

from a2a.types import Message
from agentstack_sdk.a2a.extensions import (
    FormRender,
    TextField,
    FormRequestExtensionServer,
    FormRequestExtensionSpec,
)
from agentstack_sdk.a2a.types import AgentMessage
from agentstack_sdk.server import Server
from agentstack_sdk.server.context import RunContext
from pydantic import BaseModel

server = Server()


class UserDetails(BaseModel):
    name: str | None
    email: str | None


@server.agent()
async def advanced_server_wrapper_example(
    input: Message, context: RunContext, form_request: Annotated[FormRequestExtensionServer, FormRequestExtensionSpec()]
):
    """Agent that pauses execution to request user input"""
    yield AgentMessage(text="I need some information from you.")

    # Execution pauses here - task enters input_required state
    # User fills out the form in the UI
    form_data = await form_request.request_form(
        form=FormRender(
            title="Please provide your details",
            fields=[
                TextField(id="name", label="Your Name"),
                TextField(id="email", label="Email Address"),
            ],
        ),
        model=UserDetails,
    )

    # Execution resumes after user submits the form
    if form_data:
        yield AgentMessage(text=f"Thank you, {form_data.name}! I'll contact you at {form_data.email}.")
    else:
        yield AgentMessage(text="Form was not filled out.")


def run():
    server.run(host=os.getenv("HOST", "127.0.0.1"), port=int(os.getenv("PORT", 8000)))


if __name__ == "__main__":
    run()

```

--------------------------------

### Start Local Development with Authentication Enabled

Source: https://github.com/i-am-bee/agentstack/blob/main/CONTRIBUTING.md

Starts the local development environment with authentication enabled, typically for running tests. Some tests may require additional settings as detailed in template.env.

```sh
mise run agentstack-server:dev:start --set auth.enabled=true
```

--------------------------------

### Embed Example Code in MDX

Source: https://github.com/i-am-bee/agentstack/blob/main/examples/README.md

Use embedme tags to keep documentation code samples in sync with actual tested examples.

```mdx
{/* <!-- embedme examples/agent-integration/multi-turn/basic-history/src/basic_history/agent.py --> */}
```

--------------------------------

### Configure Ollama Model Setup

Source: https://github.com/i-am-bee/agentstack/blob/main/CONTRIBUTING.md

Sets up the local model to use Ollama with a special option for true localhost access.

```sh
agentstack model setup --use-true-localhost
```

--------------------------------

### Finalize Server Entry Point

Source: https://github.com/i-am-bee/agentstack/blob/main/agents/langgraph-reflection/README.md

Implement the `run()` function to start the AgentStack server, enabling platform management.

```python
import os
def run():
    server.run(host=os.getenv("HOST", "127.0.0.1"), port=int(os.getenv("PORT", 8000)))

if __name__ == "__main__":
    run()
```

--------------------------------

### Install Agent Stack Helm Chart

Source: https://github.com/i-am-bee/agentstack/blob/main/helm/README.md

Use this command to install the agent stack helm chart from the container registry. Ensure you replace `<release-version>` with the desired version and have a `config.yaml` file for custom configurations.

```bash
helm install agentstack -f config.yaml oci://ghcr.io/i-am-bee/agentstack/chart/agentstack:<release-version>
```

--------------------------------

### Stream Provider Logs

Source: https://github.com/i-am-bee/agentstack/blob/main/docs/stable/custom-ui/platform-api-client.mdx

This example shows how to read provider logs, which are returned as a ReadableStream. It demonstrates how to get a reader and read from the stream.

```typescript
const result = await api.readProviderLogs({ id: "provider-id" });

if (result.ok && result.data) {
  const reader = result.data.getReader();
  await reader.read();
}
```

--------------------------------

### Run the Agent

Source: https://github.com/i-am-bee/agentstack/blob/main/apps/agentstack-sdk-py/README.md

Execute the Python agent script using uv. This command starts the server and makes the agent available.

```bash
uv run my_agent.py
```

--------------------------------

### Start Local Development Server

Source: https://github.com/i-am-bee/agentstack/blob/main/docs/stable/README.md

Run the Mintlify development server from the root of your documentation project. Ensure docs.json is present in the directory.

```bash
mintlify dev
```

--------------------------------

### Create and Run an Example Agent

Source: https://github.com/i-am-bee/agentstack/blob/main/apps/agentstack-sdk-py/README.md

Defines a simple agent that greets the user and demonstrates how to run it. Ensure the HELLO_TEMPLATE environment variable is set for custom greetings.

```python
import os

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.a2a.types import AgentMessage

server = 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__":
    run()
```

--------------------------------

### Tutorial/How-To Image Prompt

Source: https://github.com/i-am-bee/agentstack/blob/main/agents/deepagents_content_builder/src/content_builder/skills/blog-post/SKILL.md

Example prompt for generating a cover image for a tutorial or how-to blog post, emphasizing hands-on interaction.

```text
Clean flat illustration of hands typing on a keyboard with abstract code symbols floating upward, transforming into lightbulbs and gears. Warm gradient background from soft coral to light peach. Friendly, approachable style. Centered composition with space for text overlay.
```

--------------------------------

### agentstack self install

Source: https://github.com/i-am-bee/agentstack/blob/main/docs/stable/reference/cli-reference.mdx

Installs the Agent Stack platform pre-requisites.

```APIDOC
## `agentstack self install`

Install Agent Stack platform pre-requisites.

**Usage**:

```console
$ agentstack self install [OPTIONS]
```

**Options**:

* `-v, --verbose`: Show verbose output
* `-y, --yes`: Skip confirmation prompts
* `--help`: Show this message and exit.
```

--------------------------------

### Initialization

Source: https://github.com/i-am-bee/agentstack/blob/main/docs/stable/custom-ui/platform-api-client.mdx

Create an API client by calling `buildApiClient` with configuration options.

```APIDOC
## Initialization

Create an API client by calling `buildApiClient` with configuration options:

```typescript
import { buildApiClient } from "agentstack-sdk";

const api = buildApiClient({
  baseUrl: "https://your-agentstack-instance.com",
  fetch: customFetch, // Optional: provide custom fetch implementation
});
```

### Configuration Options

- `baseUrl` (required): The base URL of your AgentStack server instance.
- `fetch` (optional): Custom fetch implementation. Required in Node.js < 18 or environments without global fetch support. Useful for adding authentication headers or custom request handling.
```

--------------------------------

### Install Agent Stack SDK

Source: https://github.com/i-am-bee/agentstack/blob/main/apps/agentstack-sdk-ts/README.md

Install the agentstack-sdk and @a2a-js/sdk packages using npm.

```bash
npm install agentstack-sdk @a2a-js/sdk
```

--------------------------------

### Two-Step Agent Build Process

Source: https://github.com/i-am-bee/agentstack/blob/main/docs/stable/deploy-agents/deploy-your-agents.mdx

Perform a two-step build process for more control. First, build and copy the agent to the Agent Stack VM, then register it.

```bash
# Step 1: Build and copy to Agent Stack VM
agentstack build https://github.com/myorg/myrepo

# Step 2: Register the agent
agentstack add agentstack.local/my-agent-abc123:latest
```

--------------------------------

### Basic Tool Call Approval with BeeAI Framework

Source: https://github.com/i-am-bee/agentstack/blob/main/docs/stable/agent-integration/tool-calls.mdx

This example demonstrates how to integrate the Approval Extension into a BeeAI Framework agent to request user approval before executing a tool. It shows the necessary imports, extension injection, and the handler logic for requesting and processing approval.

```python
# Copyright 2025 © BeeAI a Series of LF Projects, LLC
# SPDX-License-Identifier: Apache-2.0
import os
from typing import Annotated, Any

from a2a.types import Message, TextPart
from agentstack_sdk.a2a.extensions import (
    ApprovalExtensionParams,
    ApprovalExtensionServer,
    ApprovalExtensionSpec,
    ToolCallApprovalRequest,
)
from agentstack_sdk.server import Server
from agentstack_sdk.server.context import RunContext
from beeai_framework.adapters.mcp.serve.server import _tool_factory
from beeai_framework.agents.requirement import RequirementAgent
from beeai_framework.agents.requirement.requirements.ask_permission import AskPermissionRequirement
from beeai_framework.backend import ChatModel
from beeai_framework.tools import AnyTool
from beeai_framework.tools.think import ThinkTool

server = Server()


@server.agent()
async def basic_approve_example(
    input: Message,
    context: RunContext,
    approval_ext: Annotated[ApprovalExtensionServer, ApprovalExtensionSpec(params=ApprovalExtensionParams())],
):
    async def handler(tool: AnyTool, input: dict[str, Any]) -> bool:

        response = await approval_ext.request_approval(
            # using MCP Tool data model as intermediary to simplify conversion
            ToolCallApprovalRequest.from_mcp_tool(_tool_factory(tool), input=input),
            context=context,
        )
        return response.approved

    think_tool = ThinkTool()
    agent = RequirementAgent(
        llm=ChatModel.from_name(os.getenv("LLM_MODEL", "ollama:gpt-oss:20b")),
        tools=[think_tool],
        requirements=[AskPermissionRequirement([think_tool], handler=handler)],
    )

    result = await agent.run("".join(part.root.text for part in input.parts if isinstance(part.root, TextPart)))
    yield result.output[0].text


def run():
    server.run(host=os.getenv("HOST", "127.0.0.1"), port=int(os.getenv("PORT", 8000)))


if __name__ == "__main__":
    run()

```

--------------------------------

### Install Agent Stack SDK

Source: https://github.com/i-am-bee/agentstack/blob/main/apps/beeai-web/src/modules/blog/posts/introducing-agent-stack.mdx

Use this command to install the latest Agent Stack SDK for Python.

```bash
pip install agentstack-sdk
```

--------------------------------

### Run Local Docs Development Server

Source: https://github.com/i-am-bee/agentstack/blob/main/CONTRIBUTING.md

Preview documentation locally with a development server that auto-refreshes on changes to MDX files.

```bash
mise docs:run
```

--------------------------------

### Agent Stack CLI Usage Examples

Source: https://github.com/i-am-bee/agentstack/blob/main/README.md

Demonstrates common commands for interacting with the Agent Stack CLI, including launching the web UI, listing agents, running agents, and viewing agent information.

```sh
agentstack ui
```

```sh
agentstack list
```

```sh
agentstack run chat "Hi, who are you"
```

```sh
agentstack run chat
```

```sh
agentstack info chat
```

```sh
agentstack --help
```

--------------------------------

### Install WSL (Windows)

Source: https://github.com/i-am-bee/agentstack/blob/main/docs/stable/introduction/quickstart.mdx

Update and install the Windows Subsystem for Linux (WSL). This is a prerequisite for running Agent Stack on Windows.

```powershell
wsl.exe --update
```

```powershell
wsl.exe --install
```

--------------------------------

### Agent with LLM Access Example

Source: https://github.com/i-am-bee/agentstack/blob/main/docs/stable/agent-integration/llm-proxy-service.mdx

This agent demonstrates how to access and configure the LLM service. It checks for LLM availability and retrieves configuration details like API model, key, and base URL.

```python
import os
from typing import Annotated

from a2a.types import Message
from a2a.utils.message import get_message_text
from agentstack_sdk.a2a.extensions import LLMServiceExtensionServer, LLMServiceExtensionSpec
from agentstack_sdk.a2a.types import AgentMessage
from agentstack_sdk.server import Server

server = Server()


@server.agent()
async def llm_access_example(
    input: Message,
    llm: Annotated[
        LLMServiceExtensionServer,
        LLMServiceExtensionSpec.single_demand(suggested=("ibm/granite-3-3-8b-instruct",))
    ],
):
    """Agent that uses LLM inference to respond to user input"""

    if llm and llm.data and llm.data.llm_fulfillments:
        # Extract the user's message
        user_message = get_message_text(input)

        # Get LLM configuration
        # Single demand is resolved to default (unless specified otherwise)
        llm_config = llm.data.llm_fulfillments.get("default")

        if llm_config:
            # Use the LLM configuration with your preferred client
            # The platform provides OpenAI-compatible endpoints
            api_model = llm_config.api_model
            api_key = llm_config.api_key
            api_base = llm_config.api_base

            yield AgentMessage(text=f"LLM access configured for model: {api_model}")
        else:
            yield AgentMessage(text="LLM configuration not found.")
    else:
        yield AgentMessage(text="LLM service not available.")


def run():
    server.run(host=os.getenv("HOST", "127.0.0.1"), port=int(os.getenv("PORT", 8000)))


if __name__ == "__main__":
    run()

```

--------------------------------

### Get or Refresh a Connector

Source: https://github.com/i-am-bee/agentstack/blob/main/docs/stable/experimental/connectors.mdx

Retrieve a specific connector by its ID or refresh an existing connector instance to get its latest state.

```python
# Get a specific connector
connector = await Connector.get(connector_id)

# Refresh an existing connector instance
connector = await connector.refresh()
```

--------------------------------

### Call Agent with Context Token

Source: https://github.com/i-am-bee/agentstack/blob/main/docs/stable/custom-ui/permissions-and-tokens.mdx

Demonstrates how to create a context, generate a token with specified permissions, configure agent extensions with this token, and execute an agent run. Ensure you replace 'your_provider_id' with your actual provider ID.

```python
from datetime import timedelta

import httpx
from a2a.client import ClientConfig, ClientFactory
from a2a.types import Message, Part, Role, TextPart

from agentstack_sdk.platform import ModelProvider, Provider, ModelCapability
from agentstack_sdk.platform.context import Permissions, ContextPermissions, Context
from agentstack_sdk.a2a.extensions import (
    LLMServiceExtensionClient,
    LLMServiceExtensionSpec,
    EmbeddingServiceExtensionClient,
    EmbeddingServiceExtensionSpec,
    PlatformApiExtensionClient,
    PlatformApiExtensionSpec,
    LLMFulfillment,
    EmbeddingFulfillment,
)
from uuid import uuid4


async def call_agent(
    provider: Provider,  # any agent from Provider.list() call
):
    # 1. Create context and generate token
    context = await Context.create(provider_id="your_provider_id")

    context_token = await context.generate_token(
        grant_global_permissions=Permissions(
            llm={"*"}, embeddings={"*"}, a2a_proxy={"*"}
        ),
        grant_context_permissions=ContextPermissions(
            files={"*"}, vector_stores={"*"}, context_data={"*"}
        ),
    )

    # 2. Get agent card and prepare extension specs
    agent_card = provider.agent_card
    llm_spec = LLMServiceExtensionSpec.from_agent_card(agent_card)
    embedding_spec = EmbeddingServiceExtensionSpec.from_agent_card(agent_card)
    platform_spec = PlatformApiExtensionSpec.from_agent_card(agent_card)

    # 3. Build extension metadata with context token
    metadata = {}

    # LLM extension - token passed as api_key
    if llm_spec:
        metadata |= LLMServiceExtensionClient(llm_spec).fulfillment_metadata(
            llm_fulfillments={
                key: LLMFulfillment(
                    api_base="{platform_url}/api/v1/openai/",
                    api_key=context_token.token.get_secret_value(),
                    api_model=(
                        await ModelProvider.match(
                            suggested_models=demand.suggested,
                            capability=ModelCapability.LLM,
                        )
                    )[0].model_id,
                )
                for key, demand in llm_spec.params.llm_demands.items()
            }
        )

    # Embedding extension - token passed as api_key
    if embedding_spec:
        metadata |= EmbeddingServiceExtensionClient(
            embedding_spec
        ).fulfillment_metadata(
            embedding_fulfillments={
                key: EmbeddingFulfillment(
                    api_base="{platform_url}/api/v1/openai/",
                    api_key=context_token.token.get_secret_value(),
                    api_model=(
                        await ModelProvider.match(
                            suggested_models=demand.suggested,
                            capability=ModelCapability.EMBEDDING,
                        )
                    )[0].model_id,
                )
                for key, demand in embedding_spec.params.embedding_demands.items()
            }
        )

    # 4. Create message and run agent
    message = Message(
        message_id=str(uuid4()),
        parts=[Part(root=TextPart(text="Hello, agent!"))],
        role=Role.user,
        context_id=context.id,  # Use the Context ID we just created
        metadata=metadata,
    )

    # 5. Execute agent run
    async with httpx.AsyncClient(
        # Add context token from before
        headers={"Authorization": f"Bearer {context_token.token.get_secret_value()}"},
        follow_redirects=True,
        timeout=timedelta(hours=1).total_seconds(),
    ) as httpx_client:
        conf = ClientConfig(httpx_client=httpx_client, use_client_preference=True)
        a2a_client = ClientFactory(conf).create(card=agent_card)
        async for event in a2a_client.send_message(message):
            # Handle agent responses
            print(event)

```

--------------------------------

### Agent Stack Model Setup Command

Source: https://github.com/i-am-bee/agentstack/blob/main/docs/stable/reference/cli-reference.mdx

Interactively sets up LLM and embedding provider environment variables. This command is restricted to administrators. Use the -y flag to skip confirmation prompts.

```console
$ agentstack model setup [OPTIONS]
```

--------------------------------

### Install uv via PowerShell Script (Windows)

Source: https://github.com/i-am-bee/agentstack/blob/main/docs/stable/introduction/quickstart.mdx

Recommended method to install uv on Windows using a PowerShell execution policy bypass.

```powershell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```

--------------------------------

### Run Local Keycloak Instance with Theme

Source: https://github.com/i-am-bee/agentstack/blob/main/apps/keycloak-theme/README.md

Execute this command to start a local Keycloak instance with the custom theme loaded. Refer to Keycloakify documentation for further testing details.

```bash
mise run keycloak-theme:run
```

--------------------------------

### Install Agent Stack CLI

Source: https://github.com/i-am-bee/agentstack/blob/main/README.md

Installs the Agent Stack command-line interface using a one-line script. This script is compatible with Linux and macOS.

```sh
sh -c "$(curl -LsSf https://agentstack.beeai.dev/install.sh)"
```

--------------------------------

### Create GitHub Connector with Preset

Source: https://github.com/i-am-bee/agentstack/blob/main/docs/stable/experimental/connectors.mdx

Example of creating a GitHub connector using a preset. The system automatically applies the preset's client credentials and metadata if not provided in the request.

```json
POST /connectors
{
  "url": "https://api.githubcopilot.com/mcp"
}
```

--------------------------------

### Embed Example in MDX Docs

Source: https://github.com/i-am-bee/agentstack/blob/main/CONTRIBUTING.md

This is an example of how to embed agent code directly into MDX documentation files. After scaffolding, use this tag to link the agent's Python file.

```mdx
{/* <!-- embedme examples/<path>/src/<name>/agent.py --> */}
```

--------------------------------

### Create a Connector

Source: https://github.com/i-am-bee/agentstack/blob/main/docs/stable/experimental/connectors.mdx

Create a new connector instance. This can include client credentials and custom metadata. `match_preset=True` uses default configurations.

```python
connector = await Connector.create(
    url="https://api.githubcopilot.com/mcp",
    client_id="optional_id",
    client_secret="optional_secret",
    metadata={"custom": "data"},
    match_preset=True
)
```

--------------------------------

### Example Agent Using ACP Await

Source: https://github.com/i-am-bee/agentstack/blob/main/docs/stable/community/community-calls/17-06-2025.md

This Python example demonstrates how to implement an agent that leverages the ACP Await feature for flow interventions, allowing it to pause and wait for external input.

```python
from beeai_framework.agent import Agent
from beeai_platform.acp import ACP

class RequirementAgent(Agent):
    async def handle(self, acp: ACP):
        await acp.send_message("Hello! I need some input.")
        response = await acp.wait_for_input()
        await acp.send_message(f"You said: {response}")

```

--------------------------------

### List Connectors

Source: https://github.com/i-am-bee/agentstack/blob/main/docs/stable/reference/cli-reference.mdx

Lists all configured connectors.

```console
agentstack connector list [OPTIONS]
```

--------------------------------

### Run the Agent Server

Source: https://github.com/i-am-bee/agentstack/blob/main/docs/stable/deploy-agents/building-agents.mdx

Configures and starts the agent server. It allows customization of the host and port through environment variables, with default values for local development.

```python
def run():
    server.run(host=os.getenv("HOST", "127.0.0.1"), port=int(os.getenv("PORT", 8000)))


if __name__ == "__main__":
    run()
```