### Install and Initialize AgentOven CLI

Source: https://docs.agentoven.dev/

Installs the AgentOven CLI and initializes a new AgentOven project. This is the first step to getting an agent running.

```bash
$ cargo install agentoven-cli
$ agentoven init my-kitchen
🏺 Created agentoven.toml
```

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

### Quick Start with AgentOven Rust SDK

Source: https://docs.agentoven.dev/sdk-rust

Connect to AgentOven, register an agent with specified skills, bake it, and send a task. This example demonstrates basic agent interaction.

```rust
use agentoven_core::{AgentOven, AgentConfig};

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let oven = AgentOven::connect("http://localhost:8080").await?;

    let cfg = AgentConfig::builder()
        .name("research-bot")
        .framework("langchain")
        .skills(vec!["web-search", "summarization"])
        .build();

    oven.agents().register(cfg).await?;
    oven.agents().bake("research-bot").await?;

    let result = oven.a2a()
        .send_task("research-bot", "Summarize AI safety papers")
        .await?;
    println!("{}", result.text());
    Ok(())
}
```

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

### Install Python SDK

Source: https://docs.agentoven.dev/installation

Installs the Python SDK. Requires Python 3.10+. Optionally install with async support.

```bash
$ pip install agentoven
# or with optional async support
$ pip install agentoven[async]
```

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

### Install AgentOven SDK

Source: https://docs.agentoven.dev/sdk-python

Install the AgentOven SDK using pip. Include the `[async]` extra for asynchronous support.

```bash
pip install agentoven
# With async support
pip install agentoven[async]
```

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

### Quick Start

Source: https://docs.agentoven.dev/sdk-python

Demonstrates how to connect to the control plane, register an agent, bake it, and send a task.

```APIDOC
## Quick Start

This example shows the basic usage of the Python SDK to interact with the AgentOven control plane.

```python
from agentoven import AgentOven, Agent

# Connect to control plane
oven = AgentOven("http://localhost:8080")

# Register an agent
agent = Agent(
    name="research-bot",
    framework="langchain",
    skills=["web-search", "summarization"],
)
ovel.agents.register(agent)

# Deploy
oven.agents.bake("research-bot")

# Send task via A2A
result = oven.a2a.send_task(
    agent="research-bot",
    message="Summarize AI safety papers",
)
print(result.text)
```
```

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

### Install AgentOven TypeScript SDK

Source: https://docs.agentoven.dev/sdk-typescript

Install the SDK using npm, yarn, or pnpm.

```bash
$ npm install @agentoven/sdk
# or
$ yarn add @agentoven/sdk
# or
$ pnpm add @agentoven/sdk
```

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

### Install AgentOven CLI with npm

Source: https://docs.agentoven.dev/installation

Installs the AgentOven CLI globally using npm.

```bash
$ npm install -g @agentoven/cli
✓ Installed @agentoven/cli globally
```

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

### Quick Start with AgentOven SDK

Source: https://docs.agentoven.dev/sdk-python

Connect to the AgentOven control plane, register a new agent, bake it for deployment, and send a task.

```python
from agentoven import AgentOven, Agent

# Connect to control plane
oven = AgentOven("http://localhost:8080")

# Register an agent
agent = Agent(
    name="research-bot",
    framework="langchain",
    skills=["web-search", "summarization"],
)
oven.agents.register(agent)

# Deploy
oven.agents.bake("research-bot")

# Send task via A2A
result = oven.a2a.send_task(
    agent="research-bot",
    message="Summarize AI safety papers",
)
print(result.text)
```

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

### Quick Start with AgentOven TypeScript SDK

Source: https://docs.agentoven.dev/sdk-typescript

Initialize the SDK and interact with agents for registration, baking, and sending tasks.

```typescript
import { AgentOven } from "@agentoven/sdk";

const oven = new AgentOven("http://localhost:8080");

await oven.agents.register({
  name: "research-bot",
  framework: "langchain",
  skills: ["web-search", "summarization"],
});

await oven.agents.bake("research-bot");

const result = await oven.a2a.sendTask({
  agent: "research-bot",
  message: "Summarize AI safety papers",
});
console.log(result.text);
```

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

### Managing Agents

Source: https://docs.agentoven.dev/sdk-python

Provides examples of how to list, get status, cool, and re-bake agents using the Python SDK.

```APIDOC
## Managing Agents

This section covers common operations for managing agents, such as listing, checking status, and deployment.

```python
from agentoven import AgentOven

oven = AgentOven("http://localhost:8080")

# List all agents
agents = oven.agents.list()
for a in agents:
    print(f"{a.name} — {a.status} — {a.tasks_completed} tasks")

# Get agent status
status = oven.agents.status("research-bot")
print(f"Uptime: {status.uptime}")
print(f"Health: {status.health}")

# Cool an agent
oven.agents.cool("research-bot")

# Re-bake
oven.agents.bake("research-bot")
```
```

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

### Start AgentOven Dashboard

Source: https://docs.agentoven.dev/cli

Starts the control plane and opens the dashboard UI. Use `--port` to specify the server port and `--no-open` to prevent automatic browser opening. The `server-bin` flag can set the control plane binary path.

```bash
agentoven dashboard [--port <port>] [--no-open] [--server-bin <path>]
```

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

### Install AgentOven CLI

Source: https://docs.agentoven.dev/cli

Install the AgentOven CLI using cargo, from source, or via Homebrew on macOS.

```bash
cargo install agentoven-cli
```

```bash
git clone https://github.com/agentoven/agentoven.git
cd agentoven
cargo install --path crates/agentoven-cli
```

```bash
brew install agentoven/tap/agentoven
```

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

### Start AgentOven Control Plane with Docker Compose

Source: https://docs.agentoven.dev/quickstart

Set up and run the AgentOven control plane locally using Docker Compose. This command starts PostgreSQL, Redis, and the AgentOven service.

```bash
$ cd infrastructure && docker compose up -d
✓ postgres   — running on :5432
✓ redis      — running on :6379
✓ agentoven  — running on :8080
```

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

### Install AgentOven CLI with Cargo

Source: https://docs.agentoven.dev/installation

Installs the primary Rust-based CLI for managing AgentOven resources. Verify the installation by checking the version.

```bash
$ cargo install agentoven-cli
✓ Installed agentoven v0.1.0

# Verify
$ agentoven --version
agentoven 0.1.0
```

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

### Install AgentOven Rust SDK

Source: https://docs.agentoven.dev/sdk-rust

Install the AgentOven Rust SDK using cargo. Use the 'streaming' feature for streaming support.

```terminal
$ cargo add agentoven-core
# With streaming support
$ cargo add agentoven-core --features streaming
```

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

### Install AgentOven CLI with Cargo

Source: https://docs.agentoven.dev/quickstart

Install the AgentOven CLI using Cargo, Rust's package manager. Ensure you have Rust 1.86+ installed.

```bash
$ cargo install agentoven-cli
✓ Installed agentoven v0.1.0
```

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

### Build and Invoke Agent with LangChain

Source: https://docs.agentoven.dev/why-agentoven

This example shows how to build an agent using LangChain and invoke it. Deployment is typically handled via LangSmith Deployment (paid) or a DIY approach, as there's no built-in registry or A2A discovery protocol.

```python
# LangChain — build an agent, deploy via LangSmith or DIY
from langchain.agents import create_agent
from langchain_openai import ChatOpenAI

agent = create_agent(
    model="gpt-4o",
    tools=[get_weather],
    system_prompt="You are a helpful assistant",
)
result = agent.invoke({"messages": [...]})

# Deployment options: LangSmith Deployment (paid) or DIY.
# No built-in agent registry or A2A discovery protocol.
# Other teams can't discover your agent via a standard protocol.
```

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

### Install TypeScript SDK

Source: https://docs.agentoven.dev/installation

Installs the TypeScript SDK for Node.js environments. Requires Node.js 18+.

```bash
$ npm install @agentoven/sdk
# or
$ yarn add @agentoven/sdk
```

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

### Get Model Provider Details

Source: https://docs.agentoven.dev/cli

Retrieve the configuration details for a specific model provider.

```bash
agentoven provider get <name>
```

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

### LangSmith Observability Setup

Source: https://docs.agentoven.dev/why-agentoven

Set environment variables to enable LangSmith tracing for supported frameworks. Note the free tier limitations and per-seat costs for teams.

```python
# LangSmith — framework-agnostic observability (free tier available)
import os
os.environ["LANGSMITH_TRACING"] = "true"
os.environ["LANGSMITH_API_KEY"] = "ls_xxx"

# ✅ Traces LangChain, CrewAI, OpenAI, Anthropic, AutoGen, and more
# ✅ Powerful evaluation and prompt engineering tools
# ⚠️  Free tier: 5k traces/month, 1 seat — unusable for teams
# ⚠️  Plus: $39/seat/month — 50-person team = $23,400/year just for observability
# ❌ Proprietary SaaS — not self-hostable on free/plus plans
# ❌ Per-seat pricing scales linearly with team size
# ❌ No built-in model routing or agent lifecycle management

```

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

### Install AgentOven CLI with pip

Source: https://docs.agentoven.dev/installation

Installs a Python wrapper for the AgentOven CLI, suitable for Python-centric workflows.

```bash
$ pip install agentoven
✓ Installed agentoven CLI (Python wrapper)
```

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

### Create and Chat with a Session

Source: https://docs.agentoven.dev/cli

Create a new chat session for an agent and then interact with it. Alternatively, start chatting and a new session will be auto-created if none exists.

```bash
agentoven session create my-agent
```

```bash
agentoven session chat my-agent <session-id> --thinking
```

```bash
agentoven session chat my-agent --thinking
```

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

### Deploy AgentOven to Kubernetes with Helm

Source: https://docs.agentoven.dev/deployment

Install AgentOven on a Kubernetes cluster using Helm. This command sets up the control plane with 3 replicas and enables PostgreSQL, Redis, and observability components.

```bash
$ helm repo add agentoven https://charts.agentoven.dev
$ helm install agentoven agentoven/agentoven \
    --namespace agentoven --create-namespace \
    --set controlPlane.replicas=3 \
    --set postgres.enabled=true \
    --set redis.enabled=true \
    --set observability.enabled=true
```

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

### Get Agent Details

Source: https://docs.agentoven.dev/cli

Retrieve details for a specific agent. Supports version pinning to get a particular version of the agent.

```bash
agentoven agent get <name>
```

```bash
agentoven agent get summarizer@1.2.0
```

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

### LangChain RAG Pipeline Setup

Source: https://docs.agentoven.dev/why-agentoven

Assemble a RAG pipeline using LangChain components, requiring manual selection and integration of embeddings, vector stores, and retrieval chains. Lacks built-in evaluation.

```python
# LangChain — flexible RAG, but requires assembling multiple packages
from langchain_openai import OpenAIEmbeddings
from langchain_community.vectorstores import Chroma
from langchain.text_splitter import RecursiveCharacterTextSplitter
from langchain.chains import RetrievalQA

# Powerful and flexible, but each piece is a separate dependency.
embeddings = OpenAIEmbeddings()
vectorstore = Chroma.from_documents(docs, embeddings)
chain = RetrievalQA.from_chain_type(llm, retriever=vectorstore.as_retriever())
# You choose your own vector store, embedder, and retrieval chain.
# No built-in quality evaluation (RAGAS) or ingestion pipeline.

```

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

### AgentOven CLI Configuration Management

Source: https://docs.agentoven.dev/configuration

Use these CLI commands to manage your AgentOven configuration. You can view, set, get, or reset configuration values.

```bash
# View current config
$ agentoven config show

# Set a value
$ agentoven config set server.url "https://prod.agentoven.dev"
✓ Updated server.url

# Get a value
$ agentoven config get kitchen.name
my-kitchen

# Reset to defaults
$ agentoven config reset
✓ Reset agentoven.toml to defaults

```

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

### Run RAGAS Sidecar Directly with Python

Source: https://docs.agentoven.dev/ragas

Alternatively, you can run the RAGAS sidecar directly on your machine. Ensure you have the necessary dependencies installed.

```bash
# Or run directly with Python
$ cd control-plane/internal/integrations/ragas
$ pip install fastapi uvicorn ragas langchain-openai
$ uvicorn server:app --host 0.0.0.0 --port 8400
```

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

### Configure pgvector Connection URL

Source: https://docs.agentoven.dev/vector-stores

Set the AGENTOVEN_PGVECTOR_URL environment variable to enable the pgvector store. PostgreSQL and the pgvector extension must be installed.

```bash
# Embedded store is always available (default)

# Enable pgvector (requires PostgreSQL + pgvector extension)
$ export AGENTOVEN_PGVECTOR_URL="postgres://user:pass@localhost:5432/agentoven"

# AgentOven auto-creates the vector tables on startup
```

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

### Orchestrate Agents with CrewAI

Source: https://docs.agentoven.dev/why-agentoven

This example demonstrates agent orchestration within CrewAI, allowing different LLMs per agent. However, it does not support including non-CrewAI agents (e.g., LangChain agents) in the same crew.

```python
# CrewAI — orchestration within CrewAI agents
from crewai import Agent, Task, Crew

researcher = Agent(
    role="Senior Researcher",
    goal="Research the topic thoroughly",
    backstory="You are an expert researcher.",
    llm="gpt-4o",
)
crew = Crew(agents=[researcher], tasks=[task])
result = crew.kickoff()

# Enterprise plan offers managed deployment.
# OSS version: agent is ephemeral, no registry or A2A discovery.
# Can't mix non-CrewAI agents (e.g., a LangChain agent) into a crew.
```

```python
# CrewAI — different LLMs per agent, but all must be CrewAI agents
from crewai import Agent, Task, Crew

researcher = Agent(role="Researcher", llm="gpt-4o", ...)
writer = Agent(role="Writer", llm="claude-sonnet-4-20250514", ...)  # Different LLM ✅

# What if your best summarizer is a LangChain agent?
# What if another team built a validator with the OpenAI SDK?
```

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

### Async Usage of AgentOven SDK

Source: https://docs.agentoven.dev/sdk-python

Utilize the asynchronous AgentOven client for non-blocking operations. This example shows registering, baking, and streaming responses.

```python
import asyncio
from agentoven import AsyncAgentOven, Agent

async def main():
    oven = AsyncAgentOven("http://localhost:8080")

    # Register and bake
    agent = Agent(name="fast-bot", framework="crewai", skills=["analysis"])
    await oven.agents.register(agent)
    await oven.agents.bake("fast-bot")

    # Stream response via SSE
    async for chunk in oven.a2a.send_task_stream(
        agent="fast-bot",
        message="Analyze quarterly sales data",
    ):
        print(chunk.text, end="", flush=True)

asyncio.run(main())
```

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

### AgentOven Helm Chart Values for Production

Source: https://docs.agentoven.dev/deployment

Configuration values for deploying AgentOven to Kubernetes using Helm. This example enables horizontal pod autoscaling for the control plane, configures persistence for PostgreSQL, and enables replication for Redis.

```yaml
controlPlane:
  replicas: 3
  resources:
    requests: {cpu: "500m", memory: "512Mi" }
    limits: {cpu: "2", memory: "2Gi" }
  autoscaling:
    enabled: true
    minReplicas: 2
    maxReplicas: 10
    targetCPU: 70

postgres:
  enabled: true
  persistence:
    size: 50Gi
    storageClass: managed-premium

redis:
  enabled: true
  architecture: replication
  replica:
    replicaCount: 2

observability:
  enabled: true
  prometheus:
    serviceMonitor: true
  grafana:
    dashboards: true
```

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

### Initialize AgentOven Project

Source: https://docs.agentoven.dev/cli

Initialize a new AgentOven project in the current directory. Specify a project path, agent name, and framework.

```bash
agentoven init [path] [--name <name>] [--framework <fw>]
```

```bash
agentoven init my-agent --framework openai-sdk
```

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

### agentoven init

Source: https://docs.agentoven.dev/cli

Initializes a new AgentOven project in the current directory. It creates essential project files like `agentoven.toml`, `prompts/system.md`, and `.gitignore`.

```APIDOC
## agentoven init

### Description
Initializes a new AgentOven project in the current directory.

### Usage
```bash
agentoven init [path] [--name <name>] [--framework <fw>]
```

### Parameters
#### Path Parameters
- **path** (string) - Optional - Project directory. Defaults to the current directory (`.`).

#### Flags
- **--name, -n** (string) - Optional - The name of the agent. Defaults to the directory name.
- **--framework, -f** (string) - Optional - The framework to use for the project. Options include `langgraph`, `crewai`, `openai-sdk`, `autogen`, `managed`, `custom`. Defaults to `custom`.

### Example
```bash
agentoven init my-agent --framework openai-sdk
```
```

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

### Create a New AgentOven Kitchen

Source: https://docs.agentoven.dev/quickstart

Initialize a new workspace (Kitchen) for your agents, recipes, configs, and secrets. This creates the necessary configuration and prompt files.

```bash
$ agentoven init my-kitchen
🏺 Created agentoven.toml
📝 Created prompts/system.md
✓ Kitchen 'my-kitchen' is ready
```

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

### Running Recipes

Source: https://docs.agentoven.dev/sdk-python

Shows how to execute recipes from a file, with and without parameters.

```APIDOC
## Running Recipes

This example demonstrates how to run predefined recipes, including passing custom parameters.

```python
from agentoven import AgentOven

oven = AgentOven("http://localhost:8080")

# Run a recipe from file
result = oven.recipes.run("pipeline.yaml")
print(f"Recipe completed in {result.duration}s")
print(f"Steps: {len(result.steps)}")

# Run with parameters
result = oven.recipes.run(
    "pipeline.yaml",
    params={"topic": "AI safety", "depth": "detailed"},
)
```
```

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

### Configuring MCP Tool Servers

Source: https://docs.agentoven.dev/mcp

Enable built-in MCP tool servers like 'web-search' and 'file-system' or connect external MCP-compatible tool servers by specifying their URLs and transport methods in the kitchen configuration.

```toml
[mcp]
# Built-in tools
enable = ["web-search", "file-system"]

# External MCP servers
[[mcp.servers]]
name = "my-custom-tools"
url = "http://localhost:9090/mcp"
transport = "sse"

[[mcp.servers]]
name = "company-apis"
url = "http://internal-tools:8081/mcp"
transport = "stdio"
command = "npx"
args = ["-y", "@company/mcp-tools"]
```

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

### provider get

Source: https://docs.agentoven.dev/cli

Retrieve details for a specific configured model provider.

```APIDOC
## provider get

### Description
Retrieves the configuration details for a specific model provider.

### Method
`agentoven provider get <name>`

### Parameters
#### Path Parameters
- **name** (string) - The name of the provider to retrieve.

#### Query Parameters
None

#### Flags
None

### Request Example
```bash
agentoven provider get my-openai
```

### Response
(No specific response schema documented)
```

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

### Discover Models from Provider

Source: https://docs.agentoven.dev/cli

Discover and list the models available from a specific model provider.

```bash
agentoven provider discover <name>
```

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

### Pipeline Status

Source: https://docs.agentoven.dev/rag

Get the current status and configuration of the RAG pipeline.

```APIDOC
## GET /api/v1/rag/status

### Description
Retrieve the status and configuration of the RAG pipeline.

### Method
GET

### Endpoint
/api/v1/rag/status

### Parameters
(No parameters specified in source)

### Request Example
(No request example provided in source)

### Response
#### Success Response (200)
(No specific success response schema provided in source)

#### Response Example
(No specific success response example provided in source)
```

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

### List Model Providers

Source: https://docs.agentoven.dev/cli

List all configured model providers.

```bash
agentoven provider list
```

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

### Get Agent Status

Source: https://docs.agentoven.dev/sdk-typescript

Retrieves detailed status information for a specific agent.

```APIDOC
## Get Agent Status

### Description
Fetches detailed status information for a specific agent, including its uptime and health.

### Method
```typescript
await oven.agents.status(agentName: string): Promise<{ uptime: string, health: string }>
```

### Parameters
#### `oven.agents.status`
- **agentName** (string) - Required - The name of the agent to get the status for.

### Response
#### Success Response
- **uptime** (string) - The uptime of the agent.
- **health** (string) - The health status of the agent.

### Request Example
```typescript
import { AgentOven } from "@agentoven/sdk";

const oven = new AgentOven("http://localhost:8080");

const status = await oven.agents.status("research-bot");
console.log("Uptime:", status.uptime);
console.log("Health:", status.health);
```
```

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

### Register and Deploy Agent with AgentOven

Source: https://docs.agentoven.dev/why-agentoven

Register an agent once, deploy it anywhere, and make it discoverable via the A2A protocol. This approach works with any agent framework.

```python
from agentoven import Agent, Ingredient, AgentOvenClient

agent = Agent("research-bot", ingredients=[
    Ingredient.model("gpt-4o", provider="openai"),
    Ingredient.tool("web-search", protocol="mcp"),
])

client = AgentOvenClient()
client.register(agent)       # → Agent in registry with A2A card
client.bake(agent)            # → Deployed, health-checked, discoverable
```

```terminal
$ agentoven agent register --name research-bot --framework langchain
✓ Agent 'research-bot' registered

$ agentoven agent bake research-bot
✓ Agent deployed → https://your-oven.dev/.well-known/agent.json
```

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

### agent get

Source: https://docs.agentoven.dev/cli

Retrieve details for a specific agent by name, with optional version pinning.

```APIDOC
## agent get

### Description
Retrieves detailed information about a specific agent. You can specify the agent by its name or by its name and version.

### Method
`agentoven agent get <name>`

### Parameters
#### Path Parameters
- **name** (string) - The name of the agent to retrieve. Can include a version suffix like `@1.2.0`.

#### Query Parameters
None

#### Flags
None

### Request Example
```bash
agentoven agent get summarizer
agentoven agent get summarizer@1.2.0
```

### Response
(No specific response schema documented)
```

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

### Initialize AgentOven Configuration

Source: https://docs.agentoven.dev/cli

Creates a default `agentoven.toml` configuration file. This file can be customized with agent details, model configurations, and baking environments.

```toml
[agent]
name = "my-agent"
version = "0.1.0"
description = ""
framework = "custom"

[ingredients]
# [[ingredients.models]]
# name = "gpt-4o"
# provider = "azure-openai"

[bake]
# environment = "production"

[oven]
# url = "http://localhost:8080"
# kitchen = "default"

```

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

### Managing Agents with AgentOven TypeScript SDK

Source: https://docs.agentoven.dev/sdk-typescript

List agents, get their status, and manage their lifecycle (cool and re-bake).

```typescript
import { AgentOven } from "@agentoven/sdk";

const oven = new AgentOven("http://localhost:8080");

// List all agents
const agents = await oven.agents.list();
for (const agent of agents) {
  console.log(agent.name, agent.status, agent.tasksCompleted);
}

// Get detailed status
const status = await oven.agents.status("research-bot");
console.log("Uptime:", status.uptime);
console.log("Health:", status.health);

// Cool and re-bake
await oven.agents.cool("research-bot");
await oven.agents.bake("research-bot");
```

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

### AgentOven Configuration File (agentoven.toml)

Source: https://docs.agentoven.dev/configuration

This TOML file defines various settings for your AgentOven kitchen, including metadata, server connection, authentication, default agent parameters, logging, MCP tools, and observability.

```toml
# Kitchen metadata
[kitchen]
name = "my-kitchen"
description = "Production agent workspace"
version = "0.1.0"

# Control plane connection
[server]
url = "http://localhost:8080"
timeout = 30           # seconds
retries = 3
retry_delay = 1        # seconds

# Authentication
[auth]
method = "jwt"         # jwt | api-key | none
token_path = "~/.agentoven/token"
# api_key = "sk-..."  # alternative to JWT

# Agent defaults (applied to all agents unless overridden)
[defaults.agent]
framework = "langchain"
timeout = 60
max_retries = 2
health_check_interval = 30

# Logging
[logging]
level = "info"         # debug | info | warn | error
format = "json"        # json | text
output = "stdout"      # stdout | file
# file_path = "/var/log/agentoven/kitchen.log"

# MCP Tool configuration
[mcp]
enable = ["web-search", "file-system"]

[[mcp.servers]]
name = "custom-tools"
url = "http://localhost:9090/mcp"
transport = "sse"

# Observability
[observability]
tracing = true
metrics = true
otel_endpoint = "http://localhost:4317"
service_name = "my-kitchen"

# Secrets (references to env vars or vault)
[secrets]
OPENAI_API_KEY = { env = "OPENAI_API_KEY" }
DB_PASSWORD = { vault = "secret/data/db", key = "password" }

```

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

### Register and Bake Agent

Source: https://docs.agentoven.dev/sdk-typescript

Demonstrates how to register a new agent with specified skills and then bake it, making it ready for use.

```APIDOC
## Register and Bake Agent

### Description
Registers a new agent with the specified framework and skills, then bakes the agent to prepare it for execution.

### Method
```typescript
await oven.agents.register({ name: string, framework: string, skills: string[] })
await oven.agents.bake(agentName: string)
```

### Parameters
#### `oven.agents.register`
- **name** (string) - Required - The name of the agent.
- **framework** (string) - Required - The framework the agent uses (e.g., 'langchain').
- **skills** (string[]) - Required - A list of skills the agent possesses.

#### `oven.agents.bake`
- **agentName** (string) - Required - The name of the agent to bake.

### Request Example
```typescript
import { AgentOven } from "@agentoven/sdk";

const oven = new AgentOven("http://localhost:8080");

await oven.agents.register({
  name: "research-bot",
  framework: "langchain",
  skills: ["web-search", "summarization"],
});

await oven.agents.bake("research-bot");
```
```

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

### Define CrewAI Crew

Source: https://docs.agentoven.dev/why-agentoven

This snippet shows the basic setup for a CrewAI crew, defining agents and tasks with a sequential processing flow.

```python
crew = Crew(
    agents=[researcher, writer],
    tasks=[research_task, write_task],
    process="sequential",
)
```

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

### Create and Execute a Recipe

Source: https://docs.agentoven.dev/cli

Create a new multi-agent workflow recipe from a YAML file and then execute it with specified input. Input can be a JSON string or a file.

```bash
agentoven recipe create doc-review --from recipe.yaml
```

```bash
agentoven recipe bake doc-review --input '{"document_url":"https://..."}'
```

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

### Create AgentOven Recipe with Mixed Frameworks

Source: https://docs.agentoven.dev/why-agentoven

Define a content pipeline recipe using AgentOven, integrating steps from LangChain, human gates, CrewAI, and OpenAI SDK agents within a single workflow.

```python
from agentoven import Recipe, Step, AgentOvenClient

recipe = Recipe("content-pipeline", steps=[
    # Step 1: LangChain researcher
    Step.agent("research", agent_ref="research-bot"),

    # Step 2: Human approval gate
    Step.human_gate("review", notify=["slack:#content-review"]),

    # Step 3: CrewAI writer (different framework, same workflow)
    Step.agent("write", agent_ref="content-writer"),

    # Step 4: OpenAI SDK validator (yet another framework)
    Step.agent("validate", agent_ref="quality-checker"),
])

client = AgentOvenClient()
run_id = client.bake_recipe(recipe, input={"topic": "AI in healthcare"})
```

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

### Send a Task to an Agent

Source: https://docs.agentoven.dev/quickstart

Submit a task to a deployed agent using its A2A endpoint. This example sends a summarization task to the 'research-bot' agent.

```bash
$ agentoven task send research-bot "Summarize the latest AI safety papers"
📨 Task submitted — id: task-a1b2c3
✓ Status: completed
✓ Result: "Here is a summary of recent AI safety research..."
```

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

### Clone and Run AgentOven with Docker Compose

Source: https://docs.agentoven.dev/deployment

Clone the AgentOven repository and use Docker Compose to quickly set up the full stack locally. This includes PostgreSQL, Redis, an OpenTelemetry collector, and the AgentOven service.

```bash
$ git clone https://github.com/agentoven/agentoven
$ cd agentoven/infrastructure
$ docker compose up -d
✓ postgres        — :5432
✓ redis           — :6379
✓ otel-collector  — :4317
✓ agentoven       — :8080
```

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

### Send Task via A2A

Source: https://docs.agentoven.dev/a2a

Tasks are sent as JSON-RPC 2.0 messages to an agent's A2A endpoint. This example shows how to send a task to the 'research-bot' agent.

```bash
$ curl -X POST https://oven.example.com/agents/research-bot/a2a \
    -H "Content-Type: application/json" \
    -d '{
      "jsonrpc": "2.0",
      "method": "tasks/send",
      "id": "1",
      "params": {
        "id": "task-001",
        "message": {
          "role": "user",
          "parts": [{"type":"text","text":"Summarize AI safety papers"}]
        }
      }
    }'
```

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

### Run Recipe

Source: https://docs.agentoven.dev/sdk-typescript

Executes a predefined recipe defined in YAML format, with optional parameters.

```APIDOC
## Run Recipe

### Description
Executes a recipe defined in YAML format. Allows passing parameters to customize the recipe's execution.

### Method
```typescript
await oven.recipes.run(yaml: string, options?: { params: Record<string, any> }): Promise<{ duration: number, steps: Array<{ agent: string, status: string }> }>
```

### Parameters
#### `oven.recipes.run`
- **yaml** (string) - Required - The recipe definition in YAML format.
- **options** (object) - Optional - Configuration options for the recipe run.
  - **params** (object) - Optional - Key-value pairs of parameters to pass to the recipe.

### Request Example
```typescript
import { AgentOven } from "@agentoven/sdk";
import { readFile } from "fs/promises";

const oven = new AgentOven("http://localhost:8080");

const yaml = await readFile("pipeline.yaml", "utf-8");
const result = await oven.recipes.run(yaml, {
  params: { topic: "AI safety", depth: "detailed" },
});

console.log("Completed in", result.duration, "seconds");
for (const step of result.steps) {
  console.log(step.agent, "—", step.status);
}
```

### Response
#### Success Response
- **duration** (number) - The total duration of the recipe execution in seconds.
- **steps** (Array of step objects) - An array detailing each step executed:
  - **agent** (string) - The name of the agent that executed the step.
  - **status** (string) - The status of the step (e.g., 'completed', 'failed').
```

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

### Using MCP Tools in Python

Source: https://docs.agentoven.dev/mcp

Interact with MCP tools using the AgentOven Python SDK. List available tools and call them directly with specified arguments. Ensure the AgentOven instance is correctly initialized with the control plane URL.

```python
from agentoven import AgentOven

oven = AgentOven("http://localhost:8080")

# List available MCP tools
tools = oven.mcp.list_tools()
for tool in tools:
    print(f"{tool.name}: {tool.description}")

# Call a tool directly
result = oven.mcp.call_tool(
    name="web-search",
    arguments={"query": "AI safety research 2025", "max_results": 3},
)
for item in result.content:
    print(item.text)
```

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

### Agent Card Example

Source: https://docs.agentoven.dev/a2a

An Agent Card describes an agent's capabilities, skills, and supported content types, enabling automatic discovery by other agents and clients. It is published at /.well-known/agent.json.

```json
{
  "name": "research-bot",
  "description": "Research and summarization agent",
  "url": "https://oven.example.com/agents/research-bot/a2a",
  "version": "1.0.0",
  "capabilities": {
    "streaming": true,
    "pushNotifications": true
  },
  "skills": [
    {
      "id": "web-search",
      "name": "Web Search",
      "description": "Search the web for information"
    },
    {
      "id": "summarization",
      "name": "Summarization",
      "description": "Summarize long documents"
    }
  ]
}
```

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

### Deploy Agent (Bake)

Source: https://docs.agentoven.dev/cli

Deploy an agent, resolving all its ingredients and validating its configuration. This sets the agent to a ready state for use.

```bash
agentoven agent bake <name>
```

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

### Add a Prompt Template

Source: https://docs.agentoven.dev/cli

Add a new versioned prompt template. Specify the template content and its variables. Variables should be comma-separated.

```bash
agentoven prompt add summarizer-system \
  --template "You are a {role}. Summarize the following in {format} format." \
  --variables "role,format"
```

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

### Register Agent from Definition File

Source: https://docs.agentoven.dev/cli

Register a new agent using a YAML, JSON, or TOML definition file. This is a convenient way to define complex agents.

```bash
agentoven agent register --from agent.yaml
```

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

### Register OpenAI Provider via API

Source: https://docs.agentoven.dev/embeddings

Register an OpenAI provider using the API. Embeddings will be automatically discovered and available after registration. Use this to integrate OpenAI's embedding models into your AgentOven setup.

```bash
$ curl -X POST http://localhost:8080/api/v1/providers \
  -H "Content-Type: application/json" \
  -H "X-Kitchen: default" \
  -d '{
    "name": "my-openai",
    "kind": "openai",
    "config": { "api_key": "sk-..." },
    "models": ["gpt-4o", "gpt-4o-mini"]
  }'

# Embeddings are now auto-available!
$ curl http://localhost:8080/api/v1/embeddings/drivers
```

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

### Run Recipes with AgentOven SDK

Source: https://docs.agentoven.dev/sdk-python

Execute recipes defined in YAML files, with options to pass parameters for dynamic execution.

```python
from agentoven import AgentOven

oven = AgentOven("http://localhost:8080")

# Run a recipe from file
result = oven.recipes.run("pipeline.yaml")
print(f"Recipe completed in {result.duration}s")
print(f"Steps: {len(result.steps)}")

# Run with parameters
result = oven.recipes.run(
    "pipeline.yaml",
    params={"topic": "AI safety", "depth": "detailed"},
)
```

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

### Bake and Deploy an Agent with AgentOven

Source: https://docs.agentoven.dev/

Bakes a registered agent, making it ready for use. The agent will be available at a specific A2A endpoint.

```bash
$ agentoven agent bake research-bot
🔥 Baking agent 'research-bot'... done!
✓ Agent is hot and ready at /agents/research-bot/a2a
```

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

### Register Agent with AgentOven

Source: https://docs.agentoven.dev/why-agentoven

Use this command to register an agent with AgentOven. This is part of the agent's production lifecycle management.

```bash
agentoven agent register
```

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

### Deploy Agent with AgentOven

Source: https://docs.agentoven.dev/why-agentoven

Use this command to bake (deploy) an agent using AgentOven. This command is part of the built-in deployment capabilities.

```bash
agentoven agent bake
```

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

### Apply Manifests with AgentOven CLI

Source: https://docs.agentoven.dev/cli

Manage AgentOven resources declaratively using YAML, JSON, or TOML manifest files. Supports multi-document manifests and dry-run previews.

```bash
agentoven apply -f <manifest-file> [--dry-run]
```

```yaml
# agent.yaml — multi-document manifest
kind: Agent
name: summarizer
description: "Summarizes documents with citations"
model_provider: openai
model_name: gpt-4o
system_prompt: "You are a document summarizer."
tags:
  - production
ingredients:
  models:
    - name: gpt-4o
      provider: openai
      role: primary
  tools:
    - name: web-search
      protocol: mcp
---
kind: ToolSet
tools:
  - name: web-search
    description: "Search the web for information"
    endpoint: https://tools.example.com/search
    transport: http
  - name: calculator
    description: "Perform math calculations"
    endpoint: https://tools.example.com/calc
---
kind: Recipe
name: doc-review
steps:
  - name: summarize
    agent: summarizer
    kind: agent
  - name: review-gate
    kind: human-gate
    depends_on:
      - summarize
  - name: publish
    agent: publisher
    kind: agent
    depends_on:
      - review-gate

```

```bash
# Apply all resources from a manifest
agentoven apply -f agent.yaml

# Preview without applying
agentoven apply -f agent.yaml --dry-run
```

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

### Register Agent with Flags

Source: https://docs.agentoven.dev/cli

Register a new agent by specifying all its properties directly via command-line flags. Useful for quick registrations or scripting.

```bash
agentoven agent register summarizer \
  --description "Summarizes documents with citations" \
  --framework managed \
  --model-provider my-openai \
  --model-name gpt-4o \
  --system-prompt "You are a document summarizer." \
  --skill summarization \
  --tag production
```

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

### Declarative AgentOven Recipe (YAML)

Source: https://docs.agentoven.dev/why-agentoven

Define an AgentOven recipe declaratively using YAML, specifying agents, human gates, and their dependencies for a content pipeline.

```yaml
# recipe.yaml — framework-agnostic DAG
name: content-pipeline
steps:
  - id: research
    agent: research-bot          # LangChain agent
  - id: review
    kind: human-gate
    notify: ["slack:#reviews"]
  - id: write
    agent: content-writer        # CrewAI agent
    depends_on: [review]
  - id: validate
    agent: quality-checker       # OpenAI SDK agent
    depends_on: [write]
```

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

### Multi-Agent Communication with AgentOven SDK

Source: https://docs.agentoven.dev/a2a

This Python snippet demonstrates how to use the AgentOven SDK to discover other agents via the Menu, read their Agent Cards, and delegate tasks using the A2A protocol.

```python
from agentoven import AgentOven

oven = AgentOven("http://localhost:8080")

# Agent discovers another agent via the Menu
menu = oven.menu.list()
writer = next(a for a in menu if "writing" in a.skills)

# Delegate a sub-task via A2A
result = oven.a2a.send_task(
    agent=writer.name,
    message="Write a blog post about these findings: ...",
)
print(result.text)
```

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

### Add Model Provider

Source: https://docs.agentoven.dev/cli

Add a new model provider configuration. Specify the provider kind, API key, base URL, and default model.

```bash
agentoven provider add <name> --kind <kind> [--api-key <key>] [--base-url <url>] [--model <model>]
```

```bash
agentoven provider add my-openai --kind openai --api-key $OPENAI_API_KEY --model gpt-4o
```

```bash
agentoven provider add local-llm --kind ollama --base-url http://localhost:11434 --model llama3
```

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

### Error Handling

Source: https://docs.agentoven.dev/sdk-python

Illustrates how to handle common exceptions that may occur when using the SDK.

```APIDOC
## Error Handling

This section provides examples of how to catch and handle specific exceptions raised by the SDK.

```python
from agentoven import AgentOven
from agentoven.exceptions import (
    AgentNotFoundError,
    TaskTimeoutError,
    RateLimitError,
)

oven = AgentOven("http://localhost:8080")

try:
    result = oven.a2a.send_task(
        agent="research-bot",
        message="Analyze data",
        timeout=30,
    )
except AgentNotFoundError:
    print("Agent not registered or not baked")
except TaskTimeoutError:
    print("Task exceeded 30s timeout")
except RateLimitError as e:
    print(f"Rate limited — retry after {e.retry_after}s")
```
```

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

### Run RAGAS Sidecar with Docker

Source: https://docs.agentoven.dev/ragas

Use this command to build the Docker image for the AgentOven RAGAS evaluator and then run it as a container. This is the recommended method for deployment.

```bash
# Using Docker (recommended)
$ docker build -t agentoven-ragas \
  -f control-plane/internal/integrations/ragas/Dockerfile .
$ docker run -p 8400:8400 agentoven-ragas
```

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

### Authenticate AgentOven CLI

Source: https://docs.agentoven.dev/cli

Logs into the control plane and saves credentials. Use `--api-key` and `--url` for authentication details.

```bash
agentoven login [--api-key <key>] [--url <url>]
```

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

### Running Recipes with AgentOven TypeScript SDK

Source: https://docs.agentoven.dev/sdk-typescript

Execute recipes by providing YAML content and parameters. Reads recipe from a file.

```typescript
import { AgentOven } from "@agentoven/sdk";
import { readFile } from "fs/promises";

const oven = new AgentOven("http://localhost:8080");

// Run a recipe
const yaml = await readFile("pipeline.yaml", "utf-8");
const result = await oven.recipes.run(yaml, {
  params: { topic: "AI safety", depth: "detailed" },
});

console.log("Completed in", result.duration, "seconds");
for (const step of result.steps) {
  console.log(step.agent, "—", step.status);
}
```

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

### Async Usage

Source: https://docs.agentoven.dev/sdk-python

Illustrates how to use the asynchronous version of the Python SDK for non-blocking operations.

```APIDOC
## Async Usage

This example demonstrates the asynchronous capabilities of the Python SDK, including streaming responses.

```python
import asyncio
from agentoven import AsyncAgentOven, Agent

async def main():
    oven = AsyncAgentOven("http://localhost:8080")

    # Register and bake
    agent = Agent(name="fast-bot", framework="crewai", skills=["analysis"])
    await oven.agents.register(agent)
    await oven.agents.bake("fast-bot")

    # Stream response via SSE
    async for chunk in oven.a2a.send_task_stream(
        agent="fast-bot",
        message="Analyze quarterly sales data",
    ):
        print(chunk.text, end="", flush=True)

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

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

### AgentOven Model Routing Configuration (Bash)

Source: https://docs.agentoven.dev/why-agentoven

Configure model providers and routing strategies using AgentOven's control plane API via cURL commands.

```bash
# Register providers with the control plane
curl -X POST http://localhost:8080/api/v1/providers -d '{
  "name": "openai-primary",
  "kind": "openai",
  "model": "gpt-4o",
  "priority": 1,
  "cost_per_1k_input": 0.005
}'

curl -X POST http://localhost:8080/api/v1/providers -d '{
  "name": "anthropic-fallback",
  "kind": "anthropic",
  "model": "claude-sonnet-4-20250514",
  "priority": 2,
  "cost_per_1k_input": 0.003
}'

# Route with strategy
curl http://localhost:8080/api/v1/models/route -d '{
  "strategy": "cost-optimized",
  "messages": [{"role": "user", "content": "Summarize this doc"}]
}'
```

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

### AgentOven Tool Registration (MCP Protocol)

Source: https://docs.agentoven.dev/why-agentoven

Register a tool with AgentOven's control plane using the MCP protocol via a cURL command. This makes the tool universally accessible.

```bash
# Register a tool once via MCP — every agent can use it
curl -X POST http://localhost:8080/api/v1/tools -d '{
  "name": "search-docs",
  "description": "Search internal documents",
  "input_schema": {
    "type": "object",
    "properties": {
      "query": { "type": "string" }
    }
  }
}'
```