### Run the Example Application

Source: https://github.com/agenta-ai/agenta/blob/main/examples/node/observability-opentelemetry/README.md

Execute this command to start the instrumented Node.js application. Ensure all dependencies are installed and the .env file is configured.

```bash
pnpm start
```

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

### Complete Example: Agenta, OpenAI, and Tracing Setup

Source: https://github.com/agenta-ai/agenta/blob/main/docs/docs/integrations/llm-providers/openai/observability.mdx

A comprehensive example demonstrating the setup for Agenta Cloud/Enterprise, OpenAI API key configuration, initialization of Agenta, and instrumentation of OpenAI calls. This code combines environment variable setup, SDK initialization, and OpenTelemetry instrumentation.

```python
import os
import agenta as ag
from opentelemetry.instrumentation.openai import OpenAIInstrumentor
import openai
import asyncio

os.environ["AGENTA_API_KEY"] = "YOUR_AGENTA_API_KEY"  # Skip if using OSS locally
os.environ["AGENTA_HOST"] = "https://cloud.agenta.ai"  # Use "http://localhost" for OSS

# highlight-next-line
ag.init()

# Set your OpenAI API key
openai.api_key = "YOUR_OPENAI_API_KEY"

# highlight-next-line
OpenAIInstrumentor().instrument()

```

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

### Agent Setup Phase Example

Source: https://github.com/agenta-ai/agenta/blob/main/web/_reference/agenta-sdk/src/auto-agenta/08-agenta-agent-product.md

Demonstrates the agent's interaction during the setup phase, where it reports on generated test cases and evaluators, and asks for confirmation before running a baseline evaluation.

```text
Agent: "Generated [N] test cases in [M] categories.
        Created [K] evaluators covering [types].
        Here are a few examples: [samples].
        Anything to adjust before I run the baseline?"
User:  "Add a test for [edge case]" / "Looks good, run it"
```

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

### Agent Onboarding Phase Example

Source: https://github.com/agenta-ai/agenta/blob/main/web/_reference/agenta-sdk/src/auto-agenta/08-agenta-agent-product.md

Example of the initial interaction when the agent is first introduced to a prompt, summarizing its analysis and recommending a starting strategy.

```text
Agent: "I've analyzed [prompt]. Here's what I found: [summary].
        I recommend starting with [strategy]. Should I proceed?"
User:  "Yes" / "Actually, focus on [specific aspect]"
```

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

### Agenta Installation Output

Source: https://github.com/agenta-ai/agenta/blob/main/examples/jupyter/prompt-management/manage-prompts-with-sdk-tutorial.ipynb

Example output after successfully installing Agenta and OpenAI libraries. This confirms the packages are installed and up-to-date.

```text
Output:
Requirement already satisfied: agenta in /home/mahmoud/code/agenta_cloud/.venv/lib/python3.12/site-packages (0.51.6)
Requirement already satisfied: openai in /home/mahmoud/code/agenta_cloud/.venv/lib/python3.12/site-packages (1.106.1)
Collecting openai
  Downloading openai-1.107.1-py3-none-any.whl.metadata (29 kB)
Requirement already satisfied: decorator<6.0.0,>=5.2.1 in /home/mahmoud/code/agenta_cloud/.venv/lib/python3.12/site-packages (from agenta) (5.2.1)
Requirement already satisfied: fastapi<0.117.0,>=0.116.0 in /home/mahmoud/code/agenta_cloud/.venv/lib/python3.12/site-packages (from agenta) (0.116.1)
Requirement already satisfied: h11>=0.16.0 in /home/mahmoud/code/agenta_cloud/.venv/lib/python3.12/site-packages (from agenta) (0.16.0)
Requirement already satisfied: httpx>=0.28.0 in /home/mahmoud/code/agenta_cloud/.venv/lib/python3.12/site-packages (from agenta) (0.28.1)
Requirement already satisfied: huggingface-hub<0.31.0 in /home/mahmoud/code/agenta_cloud/.venv/lib/python3.12/site-packages (from agenta) (0.30.2)
Requirement already satisfied: importlib-metadata<9.0,>=8.0.0 in /home/mahmoud/code/agenta_cloud/.venv/lib/python3.12/site-packages (from agenta) (8.7.0)
Requirement already satisfied: jinja2<4.0.0,>=3.1.6 in /home/mahmoud/code/agenta_cloud/.venv/lib/python3.12/site-packages (from agenta) (3.1.6)
Requirement already satisfied: litellm==1.76.0 in /home/mahmoud/code/agenta_cloud/.venv/lib/python3.12/site-packages (from agenta) (1.76.0)
Requirement already satisfied: opentelemetry-api<2.0.0,>=1.27.0 in /home/mahmoud/code/agenta_cloud/.venv/lib/python3.12/site-packages (from agenta) (1.36.0)
Requirement already satisfied: opentelemetry-exporter-otlp-proto-http<2.0.0,>=1.27.0 in /home/mahmoud/code/agenta_cloud/.venv/lib/python3.12/site-packages (from agenta) (1.36.0)
Requirement already satisfied: opentelemetry-instrumentation>=0.56b0 in /home/mahmoud/code/agenta_cloud/.venv/lib/python3.12/site-packages (from agenta) (0.57b0)
Requirement already satisfied: opentelemetry-sdk<2.0.0,>=1.27.0 in /home/mahmoud/code/agenta_cloud/.venv/lib/python3.12/site-packages (from agenta) (1.36.0)
Requirement already satisfied: pydantic>=2 in /home/mahmoud/code/agenta_cloud/.venv/lib/python3.12/site-packages (from agenta) (2.11.7)
Requirement already satisfied: python-dotenv<2.0.0,>=1.0.0 in /home/mahmoud/code/agenta_cloud/.venv/lib/python3.12/site-packages (from agenta) (1.1.1)
Requirement already satisfied: pyyaml<7.0.0,>=6.0.2 in /home/mahmoud/code/agenta_cloud/.venv/lib/python3.12/site-packages (from agenta) (6.0.2)
Requirement already satisfied: starlette<0.48.0,>=0.47.0 in /home/mahmoud/code/agenta_cloud/.venv/lib/python3.12/site-packages (from agenta) (0.47.3)
Requirement already satisfied: structlog<26.0.0,>=25.2.0 in /home/mahmoud/code/agenta_cloud/.venv/lib/python3.12/site-packages (from agenta) (25.4.0)
Requirement already satisfied: toml<0.11.0,>=0.10.2 in /home/mahmoud/code/agenta_cloud/.venv/lib/python3.12/site-packages (from agenta) (0.10.2)
Requirement already satisfied: aiohttp>=3.10 in /home/mahmoud/code/agenta_cloud/.venv/lib/python3.12/site-packages (from litellm==1.76.0->agenta) (3.12.15)
Requirement already satisfied: click in /home/mahmoud/code/agenta_cloud/.venv/lib/python3.12/site-packages (from litellm==1.76.0->agenta) (8.2.1)
Requirement already satisfied: jsonschema<5.0.0,>=4.22.0 in /home/mahmoud/code/agenta_cloud/.venv/lib/python3.12/site-packages (from litellm==1.76.0->agenta) (4.25.1)
Requirement already satisfied: tiktoken>=0.7.0 in /home/mahmoud/code/agenta_cloud/.venv/lib/python3.12/site-packages (from litellm==1.76.0->agenta) (0.11.0)
Requirement already satisfied: tokenizers in /home/mahmoud/code/agenta_cloud/.venv/lib/python3.12/site-packages (from litellm==1.76.0->agenta) (0.22.0)
Requirement already satisfied: typing-extensions>=4.8.0 in /home/mahmoud/code/agenta_cloud/.venv/lib/python3.12/site-packages (from fastapi<0.117.0,>=0.116.0->agenta) (4.15.0)
Requirement already satisfied: filelock in /home/mahmoud/code/agenta_cloud/.venv/lib/python3.12/site-packages (from huggingface-hub<0.31.0->agenta) (3.19.1)

```

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

### Start the Application

Source: https://github.com/agenta-ai/agenta/blob/main/examples/node/observability-vercel-ai/README.md

Run this command to start your application and begin sending traces.

```bash
npm start
```

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

### Clone and Setup RAG Chatbot

Source: https://github.com/agenta-ai/agenta/blob/main/examples/python/RAG_QA_chatbot/README.md

Clone the example repository and copy the environment file to begin configuration.

```bash
cd examples/python/RAG_QA_chatbot

# Copy environment file
cp env.example .env
```

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

### Install Dependencies

Source: https://github.com/agenta-ai/agenta/blob/main/docs/README.md

Run this command to install the necessary packages for the documentation project. Ensure you have Node.js and npm installed.

```bash
npm install
```

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

### Copy Environment File Example

Source: https://github.com/agenta-ai/agenta/blob/main/hosting/docker-compose/ee/README.md

Copies the example environment file to be used for configuration.

```bash
cp hosting/docker-compose/ee/env.ee.gh.example hosting/docker-compose/ee/.env.ee.gh
```

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

### Clone Agenta Repository and Checkout Main Branch

Source: https://github.com/agenta-ai/agenta/blob/main/docs/design/kubernetes-oss-ee-self-hosting/qa-plan.md

Initial setup for the QA process involves cloning the Agenta repository and checking out the main branch to start from a clean state.

```bash
git clone https://github.com/Agenta-AI/agenta
cd agenta
git checkout main
```

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

### Install SDK Dependencies

Source: https://github.com/agenta-ai/agenta/blob/main/docs/docs/contributing/guides/testing.mdx

Install project dependencies for the SDK. Run this command from the 'sdk/' directory.

```bash
uv sync
```

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

### Install Web Dependencies

Source: https://github.com/agenta-ai/agenta/blob/main/docs/docs/contributing/guides/testing.mdx

Install project dependencies for the web application. Run this command from the 'web/' directory.

```bash
pnpm install
```

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

### Install Agenta, LiteLLM, and OpenInference

Source: https://github.com/agenta-ai/agenta/blob/main/docs/docs/integrations/llm-providers/litellm/observability.mdx

Install the necessary Python packages for Agenta integration with LiteLLM.

```bash
pip install -U agenta litellm openinference-instrumentation-litellm
```

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

### Install API Dependencies

Source: https://github.com/agenta-ai/agenta/blob/main/docs/docs/contributing/guides/testing.mdx

Install project dependencies for the API. Run this command from the 'api/' directory.

```bash
uv sync
uv pip install --editable ../sdk
```

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

### Full Example with Agenta Initialization and Configuration

Source: https://github.com/agenta-ai/agenta/blob/main/docs/docs/tutorials/cookbooks/_AI-powered-code-reviews.mdx

This comprehensive example demonstrates initializing Agenta, setting up LiteLLM callbacks, defining a configuration schema, and creating an instrumented API route for an LLM application.

```python
import os
import requests
import re
import sys
from urllib.parse import urlparse
from pydantic import BaseModel, Field
import agenta as ag
import litellm
from agenta.sdk.assets import supported_llm_models
from agenta.sdk.types import MCField

#os.environ["AGENTA_API_KEY"] = "your_api_key"
ag.init()

litellm.drop_params = True
litellm.callbacks = [ag.callbacks.litellm_handler()]

prompt_system = """
You are an expert Python developer performing a file-by-file review of a pull request. You have access to the full diff of the file to understand the overall context and structure. However, focus on reviewing only the specific hunk provided.
"""

prompt_user = """
Here is the diff for the file:
{diff}

Please provide a critique of the changes made in this file.
"""

# highlight-start
class Config(BaseModel):
    system_prompt: str = prompt_system
    user_prompt: str = prompt_user
    model: str = MCField(default="gpt-3.5-turbo", choices=supported_llm_models)
# highlight-end

# highlight-next-line
@ag.route("/", config_schema=Config)
@ag.instrument()
def generate_critique(pr_url:str):
    diff = get_pr_diff(pr_url)
    # highlight-next-line
    config = ag.ConfigManager.get_from_route(schema=Config)
    response = litellm.completion(
        model=config.model,
        messages=[
            {"content": config.system_prompt, "role": "system"},
            {"content": config.user_prompt.format(diff=diff), "role": "user"},
        ],
    )
    return response.choices[0].message.content

```

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

### Install and Serve Agenta Application

Source: https://github.com/agenta-ai/agenta/blob/main/docs/drafts/custom-workflows/build-rag-application.mdx

Install the Agenta package and initialize your application. Then, serve the application variant to deploy it as an API and add it to the UI.

```bash
pip install -U agenta
agenta init
agenta variant serve app.py
```

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

### SharedEditor Quick Start Example

Source: https://github.com/agenta-ai/agenta/blob/main/web/packages/agenta-ui/src/SharedEditor/README.md

A basic example demonstrating how to use the SharedEditor component in a React application.

```APIDOC
## SharedEditor Quick Start

```tsx
import { SharedEditor } from '@agenta/ui'
import { useState } from 'react'

function MyEditor() {
  const [value, setValue] = useState('Hello World')

  return (
    <SharedEditor
      initialValue={value}
      handleChange={setValue}
      placeholder="Enter text..."
    />
  )
}
```
```

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

### Install Dependencies for Agenta and LangGraph

Source: https://github.com/agenta-ai/agenta/blob/main/examples/jupyter/integrations/langgraph-integration.ipynb

Installs necessary Python packages including agenta, langchain, langgraph, and related integrations. Ensure these are installed before proceeding with the setup.

```python
!pip install agenta langchain langgraph langchain-openai langchain-community llama-index openinference-instrumentation-langchain
```

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

### GET Request for Snippets Only

Source: https://github.com/agenta-ai/agenta/blob/main/docs/designs/snippets/RFC.md

This example demonstrates how to make a GET request to filter applications, specifically requesting only those with the type 'SNIPPET'.

```text
GET /apps?snippets=only
```

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

### Full Example: Custom Application with Agenta SDK

Source: https://github.com/agenta-ai/agenta/blob/main/docs/blog/entries/new-alpha-version-of-the-sdk-for-creating-custom-applications.mdx

A complete example demonstrating how to initialize Agenta, define a configuration schema, create a route, fetch configuration, and process a request to generate a response.

```python
import agenta as ag
from agenta import Agenta
from pydantic import BaseModel, Field

#highlight-start
ag.init()
#highlight-end

# Define the configuration of the application (that will be shown in the playground )
#highlight-start
class MyConfig(BaseModel):
    temperature: float = Field(default=0.2)
    prompt_template: str = Field(default="What is the capital of {country}?")
#highlight-end

# Creates an endpoint for the entrypoint of the application
#highlight-start
@ag.route("/", config_schema=MyConfig)
#highlight-end
def generate(country: str) -> str:
    # Fetch the config from the request
    #highlight-start
    config: MyConfig = ag.ConfigManager.get_from_route(schema=MyConfig)
    #highlight-end
    prompt = config.prompt_template.format(country=country)
    chat_completion = client.chat.completions.create(
        model="gpt-3.5-turbo",
        messages=[{"role": "user", "content": prompt}],
        temperature=config.temperature,
    )
    return chat_completion.choices[0].message.content

```

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

### Install Required Dependencies

Source: https://github.com/agenta-ai/agenta/blob/main/examples/jupyter/integrations/pydanticai-integration.ipynb

Install the necessary Python packages for PydanticAI, Logfire, and Agenta integration. This command includes example dependencies for PydanticAI.

```python
!pip install pydantic-ai[examples] logfire agenta
```

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

### Manual Agent Setup (Before SDK)

Source: https://github.com/agenta-ai/agenta/blob/main/web/_reference/agenta-sdk-ai/src/README.md

Illustrates the manual setup of an agent, including composing instructions, fetching tool schemas, and merging schemas. This approach is verbose and spans multiple files.

```typescript
// lib/agent.ts
const [instructions, schemas, refs] = await Promise.all([
  composeInstructions(MODULE_ORDER, getFallbacks(), { integrations }),
  fetchToolSchemas(),
  getApplicationRefs(),
]);
const tools = mergeAgentaSchemas(localTools, schemas);
return new ToolLoopAgent({
  model,
  instructions,
  tools,
  experimental_telemetry: { isEnabled: true, metadata: { applicationId: refs.applicationId } },
});
```

```typescript
// app/api/chat/route.ts
const tracer = otelTrace.getTracer("my-app");
const span = tracer.startSpan(`chat:${sessionId}`);
const traceId = span.spanContext().traceId;
const ctx = otelTrace.setSpan(otelContext.active(), span);
return otelContext.with(ctx, () => {
  return createAgentUIStreamResponse({
    agent,
    uiMessages: messages,
    messageMetadata: () => ({ traceId }),
    onFinish: () => { span.end(); },
    onError: () => { span.end(); },
  });
});
```

```typescript
// instrumentation.ts
initTelemetry(); // 500 lines of custom OTel setup
```

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

### Agent Setup with Agenta SDK (After SDK)

Source: https://github.com/agenta-ai/agenta/blob/main/web/_reference/agenta-sdk-ai/src/README.md

Demonstrates the simplified agent setup using the Agenta SDK. This approach is concise and requires fewer lines of code.

```typescript
// lib/agent.ts
import { createAgentWithPrompts } from "@/lib/agenta-sdk/ai";
return createAgentWithPrompts({
  model: getModel(),
  promptSlugs: [...MODULE_ORDER],
  tools: localTools,
  fallbacks: getFallbacks(),
});
```

```typescript
// app/api/chat/route.ts
import { createAgentaTracedResponse } from "@/lib/agenta-sdk/ai";
return createAgentaTracedResponse({ agent, messages, sessionId });
```

```typescript
// instrumentation.ts — not needed (auto-initializes)
```

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

### Starts With Evaluator Setup

Source: https://github.com/agenta-ai/agenta/blob/main/docs/docs/evaluation/evaluation-from-sdk/04-configuring-evaluators.mdx

Configure a 'starts with' evaluator to verify if the output begins with a specified prefix. The `case_sensitive` parameter controls whether the comparison is case-sensitive.

```python
prefix_check = builtin.auto_starts_with(
    prefix="Answer:",
    case_sensitive=True
)
```

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

### Initialize Project and Environment

Source: https://github.com/agenta-ai/agenta/blob/main/docs/drafts/custom-workflows/first-app-with-langchain.mdx

Commands to create a new project directory, initialize it with Agenta, set up a virtual environment, and install dependencies.

```bash
mkdir my-first-app; cd my-first-app
agenta init
```

```bash
python3 -m venv env
source env/bin/activate
```

```bash
pip install -r requirements.txt
```

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

### Install Required Packages

Source: https://github.com/agenta-ai/agenta/blob/main/docs/docs/tutorials/cookbooks/01-capture-user-feedback.mdx

Installs the necessary Python packages for Agenta, OpenAI API access, and automatic tracing of OpenAI calls. Use this at the beginning of your project setup.

```python
# Install required packages
# agenta - for tracing and annotation
# openai - for LLM API access
# opentelemetry.instrumentation.openai - for automatic tracing of OpenAI calls

%pip install agenta -q
%pip install openai -q
%pip install opentelemetry.instrumentation.openai -q
```

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

### API Entrypoint Wiring Example

Source: https://github.com/agenta-ai/agenta/blob/main/docs/designs/gateway-tools/specs.md

Sets up the API entrypoints by initializing DAOs, adapters, services, and routers. Includes dependency injection for components like ToolsDAO and GatewayAdapterRegistry.

```python
from oss.src.dbs.postgres.tools.dbes import ConnectionDBE
from oss.src.dbs.postgres.tools.dao import ToolsDAO
from oss.src.core.tools.adapters.composio import ComposioAdapter
from oss.src.core.tools.adapters.registry import GatewayAdapterRegistry
from oss.src.core.tools.service import ToolsService
from oss.src.apis.fastapi.tools.router import ToolsRouter

# DAO
tools_dao = ToolsDAO(ConnectionDBE=ConnectionDBE)

# Adapters
composio_adapter = ComposioAdapter(
    api_key=settings.composio_api_key,
)
adapter_registry = GatewayAdapterRegistry(
    adapters={"composio": composio_adapter},
)

# Service
tools_service = ToolsService(
    tools_dao=tools_dao,
    adapter_registry=adapter_registry,
)

# Router
tools = ToolsRouter(tools_service=tools_service)

app.include_router(
    router=tools.router,
    prefix="/tools",
    tags=["Tools"],
)
```

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

### Start Full Stack and Run Migrations

Source: https://github.com/agenta-ai/agenta/blob/main/docs/docs/self-host/03-upgrading.mdx

Start the complete Agenta stack, including the web UI and Traefik, and then execute database migrations if required by the new release.

```bash
docker compose -f hosting/docker-compose/oss/docker-compose.gh.yml --env-file hosting/docker-compose/oss/.env.oss.gh --profile with-web --profile with-traefik up -d

docker ps | grep api
docker exec -e PYTHONPATH=/app -w /app/oss/databases/postgres/migrations/core <api-container-name> \
  alembic -c alembic.ini upgrade head
```

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

### Install Dependencies for Agenta and OpenAI Agents

Source: https://github.com/agenta-ai/agenta/blob/main/docs/docs/integrations/frameworks/openai-agents/observability.mdx

Install the core Agenta SDK, the OpenAI Agents framework, and the OpenInference instrumentation library for OpenAI Agents. This setup is required before configuring the environment.

```bash
pip install agenta openinference-instrumentation-openai-agents openai-agents
```

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

### Create and Edit .env File

Source: https://github.com/agenta-ai/agenta/blob/main/examples/node/observability-opentelemetry/README.md

Copy the example environment file and add your Agenta and OpenAI API keys. This step is crucial for authentication.

```bash
cp .env.example .env
# Edit .env and add your API keys
```

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

### Catalog Response Example

Source: https://github.com/agenta-ai/agenta/blob/main/docs/designs/gateway-tools/api-reference.md

Example JSON structure for the GET /catalog endpoint, listing available tools with basic information. Schemas are omitted for performance; use POST /inspect for full details.

```json
{
  "count": 2,
  "catalog": [
    {
      "slug": "tools.gateway.gmail.SEND_EMAIL",
      "provider": "gmail",
      "name": "SEND_EMAIL",
      "display_name": "Send email",
      "description": "Send an email via Gmail",
      "input_schema": null,
      "output_schema": null
    },
    {
      "slug": "tools.gateway.gmail.READ_EMAIL",
      "provider": "gmail",
      "name": "READ_EMAIL",
      "display_name": "Read email",
      "description": "Read emails from Gmail inbox",
      "input_schema": null,
      "output_schema": null
    }
  ]
}
```

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

### Complete Google ADK Application Example with Agenta

Source: https://github.com/agenta-ai/agenta/blob/main/docs/docs/integrations/frameworks/google-adk/observability.mdx

A full example of a weather agent using Google ADK, integrated with Agenta for tracing and observability. This includes setup, instrumentation, and agent logic.

```python
import os
import nest_asyncio
import asyncio

import agenta as ag
from openinference.instrumentation.google_adk import GoogleADKInstrumentor
from google.adk.agents import Agent
from google.adk.runners import Runner
from google.adk.sessions import InMemorySessionService
from google.genai import types

# Enable nested event loops inside Jupyter
nest_asyncio.apply()

# Set up the environment
os.environ["AGENTA_API_KEY"] = "YOUR AGENTA API KEY"
os.environ["AGENTA_HOST"] = "https://cloud.agenta.ai"
os.environ["GOOGLE_API_KEY"] = "YOUR GOOGLE API KEY"

```

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

### Clone, Install, and Run Evaluation Script

Source: https://github.com/agenta-ai/agenta/blob/main/docs/docs/tutorials/rag-to-production/05-end-to-end-evaluation-sdk.mdx

This bash script clones the Agenta repository, navigates to the RAG QA Chatbot example, sets up the environment variables, installs dependencies, and runs the evaluation script.

```bash
git clone https://github.com/Agenta-AI/agenta.git
cd agenta/examples/python/RAG_QA_chatbot
cp env.example .env  # fill in your keys
uv sync
uv run scripts/evaluate_rag.py
```

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

### Run Fetch Prompt Example

Source: https://github.com/agenta-ai/agenta/blob/main/web/_reference/agenta-sdk/examples/README.md

Execute the script to demonstrate fetching a prompt from the registry.

```sh
pnpm tsx examples/fetch-prompt.ts
```

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

### Initialize Agenta Project

Source: https://github.com/agenta-ai/agenta/blob/main/docs/drafts/custom-workflows/a-more-complicated-tutorial-draft.mdx

Use the Agenta CLI to initialize a new project. Select 'start with an empty project' when prompted.

```bash
mkdir my-first-app; cd my-first-app
agenta init
```

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

### Install Agenta SDK

Source: https://github.com/agenta-ai/agenta/blob/main/docs/docs/evaluation/_evaluation-from-sdk/02-setup-configuration.mdx

Install the Agenta SDK using pip. This is the first step before initializing the client.

```bash
pip install -U agenta
```

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

### SpansRouter GET Endpoint Handler

Source: https://github.com/agenta-ai/agenta/blob/main/docs/designs/extend-meters/gap.md

This is an example of a tracing fetch endpoint that does not currently call check_entitlements or adjust a read counter.

```python
@router.get("/spans")
async def get_spans(
    request: Request,
    response: Response,
    session: AsyncSession = Depends(get_db_session),
    organization_id: int = Depends(get_organization_id),
    query: SpansQuery = Depends(SpansQuery),
    limit: int = 100,
    offset: int = 0,
) -> list[Span]:
    # ... implementation details ...
    return await service.get_spans(organization_id, query, limit, offset, session=session)
```

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

### Complete Agno Logistics Dispatch Agent Example

Source: https://github.com/agenta-ai/agenta/blob/main/docs/docs/integrations/frameworks/agno/observability.mdx

A full example of an Agno agent designed for logistics dispatch, including setup for Agenta instrumentation, simulated data, and a TrackingTool. This demonstrates how to integrate Agenta's observability features into a functional Agno application.

```python
import os
import re
from itertools import permutations
import agenta as ag
from agno.agent import Agent
from agno.models.openai import OpenAIChat
from openinference.instrumentation.agno import AgnoInstrumentor


# Set up the environment
os.environ["AGENTA_API_KEY"] = "your_agenta_api_key"
os.environ["AGENTA_HOST"] = "https://cloud.agenta.ai"  # Optional, defaults to the Agenta cloud API

# Start the Agenta SDK
ag.init()
AgnoInstrumentor().instrument()


# Simulated logistics data
tracking_data = {
    "TRK10001": "In transit at Berlin Friedrichshain Distribution Center",
    "TRK10002": "Delivered on 2025-06-14 at 18:32 in Charlottenburg",
    "TRK10003": "Out for delivery — last scanned near Tempelhofer Feld",
    "TRK10004": "Held at customs near Berlin Brandenburg Airport (BER)",
    "TRK10005": "Awaiting pickup at Berlin Hauptbahnhof Parcel Station",
}

distance_matrix = {
    "Warehouse": {"A": 10, "B": 15, "C": 20},
    "A": {"Warehouse": 10, "B": 12, "C": 5},
    "B": {"Warehouse": 15, "A": 12, "C": 8},
    "C": {"Warehouse": 20, "A": 5, "B": 8},
}

driver_load = {"Alice": 2, "Bob": 3, "Charlie": 1}


# Tool: TrackingTool
class TrackingTool:
    def __init__(self):
        self.name = "TrackingTool"
        self.description = "Provides shipment status updates given a tracking ID."

    def run(self, query: str) -> str:
        match = re.search(r"\bTRK\d+\b", query.upper())
        if not match:
            return "Please provide a valid tracking ID."

        tid = match.group(0)
        status = tracking_data.get(tid)
        return f"Status for {tid}: {status}" if status else f"No information for {tid}."

```

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

### Test Trading Agent Functionality

Source: https://github.com/agenta-ai/agenta/blob/main/examples/jupyter/integrations/agno-integration.ipynb

Example Python code to test the `handle_trading_request` function with specific queries, demonstrating how to get portfolio and market data.

```python
# Test trading functionality
trading_response = handle_trading_request(
    "Show me my AAPL holdings and current market data for GOOGL"
)
print("Trading Response:", trading_response)
```

```python
# Test portfolio overview
portfolio_overview = handle_trading_request("What is my total portfolio value?")
print("Portfolio Overview:", portfolio_overview)
```

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

### Configure API Keys

Source: https://github.com/agenta-ai/agenta/blob/main/sdks/python/oss/tests/manual/tools/README.md

Copies the example environment file and instructs on how to add your API keys for the LLM providers you intend to test. Only keys for active providers are required.

```bash
cp env.example .env
```

```bash
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GEMINI_API_KEY=...
```

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

### Create Virtual Environment and Install Dependencies

Source: https://github.com/agenta-ai/agenta/blob/main/docs/drafts/custom-workflows/a-more-complicated-tutorial-draft.mdx

Set up a Python virtual environment and install necessary dependencies including langchain, agenta, python-dotenv, and openai.

```bash
python3 -m venv env
source env/bin/activate
pip install -r requirements.txt
```

```text
langchain
agenta
python-dotenv
openai
```

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

### Get Tool Response

Source: https://github.com/agenta-ai/agenta/blob/main/docs/designs/gateway-tools/api-reference.md

This is an example of a successful response when retrieving a single tool's details. It includes the tool's configuration and status flags.

```json
{
  "tool": {
    "id": "some-secret-id",
    "provider": "gmail",
    "slug": "support_inbox",
    "name": "Support inbox",
    "description": "Primary support mailbox",
    "gateway_kind": "composio",
    "flags": {
      "is_active": true,
      "is_valid": true,
      "status": null
    },
    "created_at": "2026-02-08T10:00:00Z",
    "updated_at": "2026-02-08T10:01:30Z"
  }
}
```

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

### AgentaProvider Setup

Source: https://github.com/agenta-ai/agenta/blob/main/web/_reference/agenta-sdk/src/auto-agenta/19-sdk-ui-components-proposal.md

Example of how to set up the AgentaProvider in your application to provide context for Agenta SDK components. Ensure NEXT_PUBLIC_AGENTA_HOST and NEXT_PUBLIC_AGENTA_API_KEY are set in your environment variables.

```tsx
// app/layout.tsx or providers.tsx
import { AgentaProvider } from 'agenta-sdk/react';

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <AgentaProvider
      host={process.env.NEXT_PUBLIC_AGENTA_HOST!}
      apiKey={process.env.NEXT_PUBLIC_AGENTA_API_KEY}
    >
      {children}
    </AgentaProvider>
  );
}
```

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

### Full Integration Example

Source: https://github.com/agenta-ai/agenta/blob/main/web/_reference/agenta-sdk-mastra/src/README.md

An example demonstrating the full integration flow, including fetching prompt configurations, creating a Mastra agent, and handling chat requests with tracing.

```APIDOC
## Full Integration Example

```ts
// server.ts
import { getMastraPromptConfig, createMastraTracedStream } from "@/lib/agenta-sdk/mastra";
import { Agent } from "@mastra/core";

// 1. Get prompts from Agenta
const config = await getMastraPromptConfig({
  promptSlugs: ["voice", "onboarding"],
  environment: "development",
});

// 2. Create Mastra agent
const agent = new Agent({
  name: "my-agent",
  instructions: config.instructions,
  model: anthropic("claude-sonnet-4-20250514"),
});

// 3. Handle a request with tracing
export async function handleChat(messages, sessionId) {
  const { textStream, traceId } = await createMastraTracedStream({
    agent,
    messages,
    sessionId,
    applicationSlug: "onboarding",
  });

  return new Response(textStream, {
    headers: { "X-Agenta-Trace-Id": traceId },
  });
}
```
```

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

### Railway Setup Reusable Workflow

Source: https://github.com/agenta-ai/agenta/blob/main/docs/design/railway-preview-environments/status.md

Reusable GitHub Actions workflow that installs the Railway CLI and bootstraps the preview project, environment, domain, and services.

```yaml
.github/workflows/41-railway-setup.yml
```

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

### Install Dependencies with uv

Source: https://github.com/agenta-ai/agenta/blob/main/examples/python/custom_workflows/rag-docs-qa/README.md

Sets up a virtual environment and installs project dependencies using uv. Ensure you are in the project root directory.

```bash
uv venv
source .venv/bin/activate  # On Unix/macOS
# or
.venv\scripts\activate  # On Windows

uv pip compile requirements.in --output-file requirements.txt

uv pip sync requirements.txt
```

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

### Agenta Handler Registry Example

Source: https://github.com/agenta-ai/agenta/blob/main/docs/design/migrate-evaluator-playground/new-endpoints.md

Illustrates the structure of the handler registry, mapping URIs to specific evaluator implementations. Use `retrieve_handler` to get an implementation by its URI.

```python
HANDLER_REGISTRY = {
    "agenta": {
        "builtin": {
            "echo": {"v0": echo_v0},
            "auto_exact_match": {"v0": auto_exact_match_v0},
            "auto_regex_test": {"v0": auto_regex_test_v0},
            # ... all built-in evaluators
        }
    },
    "user": {
        "custom": {
            # User-defined evaluators go here
        }
    }
}
```

```python
handler = retrieve_handler("agenta:builtin:auto_exact_match:v0")
```

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

### Configure Environment Variables

Source: https://github.com/agenta-ai/agenta/blob/main/examples/python/custom_workflows/chain_of_prompts/Readme.md

Copy the example environment file to .env and fill in your specific keys.

```bash
cp .env.example .env
```

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

### GET /evaluators/catalog/templates/{template_key}/presets

Source: https://github.com/agenta-ai/agenta/blob/main/docs/designs/runnables/schema-types.md

Retrieves the catalog preset shape for a given evaluator template. Presets represent plain parameter payloads and are treated as parameter examples.

```APIDOC
## GET /evaluators/catalog/templates/{template_key}/presets

### Description
Retrieves the catalog preset shape for a given evaluator template. Presets are plain parameter payloads and should be treated as parameter examples, not independent schema systems. They may omit optional fields or fields irrelevant to the preset's behavior.

### Method
GET

### Endpoint
/evaluators/catalog/templates/{template_key}/presets

### Parameters
#### Path Parameters
- **template_key** (string) - Required - The unique key of the evaluator template.

### Response
#### Success Response (200)
- **key** (string) - The key of the preset.
- **data** (object) - The preset data.
  - **uri** (string) - The URI of the evaluator.
  - **parameters** (object) - The parameters for the preset. (Structure may vary)

#### Response Example
```json
{
  "key": "hallucination",
  "data": {
    "uri": "agenta:builtin:auto_ai_critique:v0",
    "parameters": {}
  }
}
```
```

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

### Console Output for Agenta Evaluation

Source: https://github.com/agenta-ai/agenta/blob/main/web/_reference/agenta-sdk/src/auto-agenta/16-wiring-overview.md

Example console output detailing the progress and completion of an Agenta evaluation run, including setup steps and final summary statistics.

```text
=== Onboarding Evaluation Runner ===

Looking up rh-onboarding app in Agenta...
  Found rh-onboarding revision: abc12345...

  Creating/updating test set...
     Test set ready (revision: def67890...)

  Creating/updating evaluators...
     4 evaluators ready

  Running local evaluation...
     [1/6] scenarios complete
     [2/6] scenarios complete
     [3/6] scenarios complete
     [4/6] scenarios complete
     [5/6] scenarios complete
     [6/6] scenarios complete

──────────────────────────────────────────────────
 Evaluation complete: uuid-of-eval
   Scenarios: 6
   Results:   24
   Errors:    none
──────────────────────────────────────────────────

View results in Agenta UI → Evaluations
Evaluation ID: uuid-of-eval
```

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

### Build and Deploy Agenta EE from Source

Source: https://github.com/agenta-ai/agenta/blob/main/hosting/docker-compose/ee/README.md

Builds all Agenta EE images from the repository source and then starts the stack using a run script.

```bash
bash ./hosting/docker-compose/run.sh --ee --gh --local --build \
  --env-file ./hosting/docker-compose/ee/.env.ee.gh
```

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

### Start Local Development Server

Source: https://github.com/agenta-ai/agenta/blob/main/docs/README.md

Use this command to start a local development server. Access the site at localhost:5000. This command is useful for previewing changes as you work.

```bash
npm run start
```

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

### Fine-Grained Subscriptions with useAtomValue

Source: https://github.com/agenta-ai/agenta/blob/main/web/packages/agenta-entities/src/shared/README.md

Subscribe to specific molecule atoms like `isDirty` for fine-grained re-renders in React components. This example shows how to use `useAtomValue` to get the dirty state of a testcase.

```typescript
// Only re-renders when isDirty changes
function DirtyIndicator({ id }: { id: string }) {
  const isDirty = useAtomValue(testcaseMolecule.atoms.isDirty(id))
  return isDirty ? <Badge>Modified</Badge> : null
}
```

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

### Initialize Agenta Client

Source: https://github.com/agenta-ai/agenta/blob/main/api/ee/tests/manual/evaluations/sdk/testset-management.ipynb

Sets up the Agenta client by configuring API key and host. It retrieves the API key from environment variables or prompts the user if not found.

```python
import os

os.environ["AGENTA_API_KEY"] = ""
os.environ["AGENTA_HOST"] = "https://cloud.agenta.ai/api"

import agenta as ag
from getpass import getpass

# Get API key from environment or prompt user
api_key = os.getenv("AGENTA_API_KEY")
if not api_key:
    os.environ["AGENTA_API_KEY"] = getpass("Enter your Agenta API key: ")

# Initialize the Agenta client
ag.init()
```

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

### Quick Start: Accessing Revision Data

Source: https://github.com/agenta-ai/agenta/blob/main/web/packages/agenta-entities/src/runnable/README.md

Use `workflowMolecule.selectors` to get revision data, input ports, output ports, and configuration directly from the molecule. Requires importing `workflowMolecule` and `useAtomValue`.

```typescript
import { workflowMolecule } from '@agenta/entities/workflow'
import { useAtomValue } from 'jotai'

// Get revision data directly from the molecule
const data = useAtomValue(workflowMolecule.selectors.data(revisionId))
const inputPorts = useAtomValue(workflowMolecule.selectors.inputPorts(revisionId))
const outputPorts = useAtomValue(workflowMolecule.selectors.outputPorts(revisionId))
const config = useAtomValue(workflowMolecule.selectors.configuration(revisionId))
```

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

### Build Instrumented Multi-Agent Translation System

Source: https://github.com/agenta-ai/agenta/blob/main/docs/docs/integrations/frameworks/openai-agents/observability.mdx

An example demonstrating a multi-agent translation system instrumented with Agenta. It includes setup, initialization, and defining specialized translation agents for Spanish, French, and German.

```python
import os
import asyncio
import agenta as ag
from agents import Agent, Runner
from openinference.instrumentation.openai_agents import OpenAIAgentsInstrumentor

# Configuration setup
os.environ["AGENTA_API_KEY"] = "your_agenta_api_key"
os.environ["AGENTA_HOST"] = "https://cloud.agenta.ai"  # Optional, defaults to the Agenta cloud API
os.environ["OPENAI_API_KEY"] = "your_openai_api_key"  # Required for OpenAI Agents SDK

# Start Agenta observability
ag.init()

# Enable OpenAI Agents instrumentation
OpenAIAgentsInstrumentor().instrument()

# Define specialized translation agents
spanish_agent = Agent(
    name="Spanish agent",
    instructions="You translate the user's message to Spanish",
)

french_agent = Agent(
    name="French agent",
    instructions="You translate the user's message to French",
)

german_agent = Agent(
    name="German agent",
    instructions="You translate the user's message to German",
)

```

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

### Create Initial Configuration and Variant

Source: https://github.com/agenta-ai/agenta/blob/main/examples/jupyter/prompt-management/how-to-prompt-management.ipynb

Instantiate the configuration model with a system prompt and a user prompt, specifying LLM parameters. Then, create a new variant of your application using this configuration.

```python
from agenta.sdk.types import PromptTemplate, Message, ModelConfig
from pydantic import BaseModel

# Creates an empty application
app = ag.AppManager.create(
    app_slug="my-completion",
    template_key="SERVICE:completion",  # we define here the app type
    # template_key="SERVICE:chat" # chat prompts
    # template_key="CUSTOM" # custom configuration (schema-less, however unless you provide a URI, you can only use the registry but not the playground)
)


# Define your configuration model it should alway be of this format for completion and chat apps
class Config(BaseModel):
    prompt: PromptTemplate


# Create the initial configuration
config = Config(
    prompt=PromptTemplate(
        messages=[
            Message(
                role="system",
                content="You are an assistant that provides concise answers",
            ),
            Message(role="user", content="Explain {{topic}} in simple terms"),
        ],
        llm_config=ModelConfig(
            model="gpt-5",
            max_tokens=150,
            temperature=0.7,
            top_p=1.0,
            frequency_penalty=0.0,
            presence_penalty=0.0,
        ),
    )
)

# Create a new variant with the first revision
variant = ag.VariantManager.create(
    parameters=config.model_dump(),
    app_slug="my-completion",
    variant_slug="default",
)
```