### Quick example: create assistant, thread, message, and run

Source: https://docs.futureagi.com/docs/command-center/api/assistants

Complete workflow to create an assistant, start a conversation, and get a response using the FutureAGI gateway. The Python SDK example uses the OpenAI SDK with a custom base URL and API key. The cURL example uses shell commands with jq to parse JSON responses and requires the OpenAI-Beta header.

```python
from openai import OpenAI

client = OpenAI(
    base_url="https://gateway.futureagi.com/v1",
    api_key="sk-agentcc-your-key",
)

# 1. Create an assistant
assistant = client.beta.assistants.create(
    name="Math Tutor",
    instructions="You are a math tutor. Explain concepts step by step.",
    model="gpt-4o",
)

# 2. Create a thread
thread = client.beta.threads.create()

# 3. Add a message
client.beta.threads.messages.create(
    thread_id=thread.id,
    role="user",
    content="Explain the Pythagorean theorem",
)

# 4. Run the assistant
run = client.beta.threads.runs.create_and_poll(
    thread_id=thread.id,
    assistant_id=assistant.id,
)

# 5. Get the response
if run.status == "completed":
    messages = client.beta.threads.messages.list(thread_id=thread.id)
    for msg in messages.data:
        if msg.role == "assistant":
            print(msg.content[0].text.value)
            break
```

```bash
# 1. Create an assistant
ASSISTANT_ID=$(curl -s -X POST https://gateway.futureagi.com/v1/assistants \
  -H "Authorization: Bearer sk-agentcc-your-key" \
  -H "Content-Type: application/json" \
  -H "OpenAI-Beta: assistants=v2" \
  -d '{
    "name": "Math Tutor",
    "instructions": "You are a math tutor. Explain concepts step by step.",
    "model": "gpt-4o"
  }' | jq -r '.id')

# 2. Create a thread
THREAD_ID=$(curl -s -X POST https://gateway.futureagi.com/v1/threads \
  -H "Authorization: Bearer sk-agentcc-your-key" \
  -H "Content-Type: application/json" \
  -H "OpenAI-Beta: assistants=v2" \
  -d '{}' | jq -r '.id')

# 3. Add a message
curl -s -X POST "https://gateway.futureagi.com/v1/threads/$THREAD_ID/messages" \
  -H "Authorization: Bearer sk-agentcc-your-key" \
  -H "Content-Type: application/json" \
  -H "OpenAI-Beta: assistants=v2" \
  -d '{"role": "user", "content": "Explain the Pythagorean theorem"}'

# 4. Create a run
RUN_ID=$(curl -s -X POST "https://gateway.futureagi.com/v1/threads/$THREAD_ID/runs" \
  -H "Authorization: Bearer sk-agentcc-your-key" \
  -H "Content-Type: application/json" \
  -H "OpenAI-Beta: assistants=v2" \
  -d "{\"assistant_id\": \"$ASSISTANT_ID\"}" | jq -r '.id')

# 5. Poll until complete, then get messages
# (poll GET /v1/threads/$THREAD_ID/runs/$RUN_ID until status is "completed")
curl -s "https://gateway.futureagi.com/v1/threads/$THREAD_ID/messages" \
  -H "Authorization: Bearer sk-agentcc-your-key" \
  -H "OpenAI-Beta: assistants=v2" | jq '.data[0].content[0].text.value'
```

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

### Install without the script

Source: https://docs.futureagi.com/docs/self-hosting/installation

Manual installation steps: copy the environment file (optional) and start the stack, then create the first user with the Django management command.

```bash
cp .env.example .env       # optional; an empty .env works for local
docker compose up -d
```

```bash
docker compose exec backend python manage.py create_user
```

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

### Quickstart: Make a chat completion request via Command Center

Source: https://docs.futureagi.com/docs/command-center

Quickstart examples showing how to make a chat completion request through the Agent Command Center gateway using the OpenAI SDK in Python, TypeScript, and via curl. All use the same base URL https://gateway.futureagi.com/v1 and the placeholder API key sk-agentcc-your-api-key-here. The Python and TypeScript examples use the OpenAI client with model gpt-4o-mini and print the response content; the curl example posts directly to the /v1/chat/completions endpoint.

```python
from openai import OpenAI

client = OpenAI(
    base_url="https://gateway.futureagi.com/v1",
    api_key="sk-agentcc-your-api-key-here"
)

response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "What is the capital of France?"}]
)
print(response.choices[0].message.content)
```

```typescript
import OpenAI from 'openai';

const client = new OpenAI({
    baseURL: 'https://gateway.futureagi.com/v1',
    apiKey: 'sk-agentcc-your-api-key-here'
});

const response = await client.chat.completions.create({
    model: 'gpt-4o-mini',
    messages: [{ role: 'user', content: 'What is the capital of France?' }]
});
console.log(response.choices[0].message.content);
```

```bash
curl -X POST https://gateway.futureagi.com/v1/chat/completions \
  -H "Authorization: Bearer sk-agentcc-your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4o-mini", "messages": [{"role": "user", "content": "What is the capital of France?"}]}'
```

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

### Install core and framework instrumentors (pip and npm)

Source: https://docs.futureagi.com/docs/observe/features/manual-tracing/set-up-tracing

Install the core instrumentation package and a framework-specific instrumentor. The Python example uses pip, the TypeScript example uses npm. The comment indicates that other framework instrumentors can be installed instead.

```bash
pip install fi-instrumentation-otel
pip install traceAI-openai   # or any other framework instrumentor
```

```bash
npm install @traceai/fi-core
npm install @traceai/openai  # or any other framework instrumentor
```

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

### Quick Example: Create and Update a Knowledge Base

Source: https://docs.futureagi.com/docs/sdk/knowledgebase

Shows the minimal workflow: instantiate KnowledgeBase, create a KB with files, then add more files later via update_kb. Requires futureagi installed and FI_API_KEY plus FI_SECRET_KEY in the environment.

```python
from fi.kb import KnowledgeBase

kb = KnowledgeBase()

# Create a knowledge base with files
kb.create_kb(
    name="product-docs",
    file_paths=["docs/guide.pdf", "docs/faq.txt"],
)

# Add more files later
kb.update_kb(
    kb_name="product-docs",
    file_paths=["docs/changelog.txt"],
)

```

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

### Initial Setup with Docker Compose

Source: https://docs.futureagi.com/docs/self-hosting/docker-compose

Clones the repository, copies the environment template, pulls the base image, and starts the full stack. First boot pulls every image from Docker Hub; nothing is built locally, so give it a few minutes the first time.

```bash
git clone https://github.com/future-agi/future-agi.git
cd future-agi
cp .env.example .env
docker pull futureagi/future-agi:v1.8.19_base
docker compose up
```

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

### Clone and install dependencies for the customer service example

Source: https://docs.futureagi.com/docs/cookbook/quickstart/instrument-and-verify

Clones the openai/openai-agents-python repository and installs the required packages for instrumentation and tracing.

```bash
git clone --depth 1 https://github.com/openai/openai-agents-python
cd openai-agents-python
pip install openai-agents fi-instrumentation-otel traceai-openai-agents
```

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

### Full example: optimize a prompt with GEPAOptimizer

Source: https://docs.futureagi.com/docs/optimization/features/using-python-sdk

Complete example of using the Python SDK to optimize a prompt with GEPAOptimizer. Requires the environment variables from the Install and authenticate section to be exported. The example defines a dataset, an initial prompt, an Evaluator with the summary_quality template, a BasicDataMapper, and runs the optimizer with max_metric_calls=150.

```python
from fi.opt.base.evaluator import Evaluator
from fi.opt.datamappers import BasicDataMapper
from fi.opt.optimizers import GEPAOptimizer

# 1. Dataset: each row is one example the optimizer scores the prompt against
dataset = [
    {
        "article": "The James Webb Space Telescope has captured its clearest images yet of a distant exoplanet's atmosphere, revealing traces of carbon dioxide and methane.",
        "target_summary": "JWST detected carbon dioxide and methane in a distant exoplanet's atmosphere.",
    },
    {
        "article": "Researchers have discovered a new enzyme that breaks down PET plastic at room temperature, far faster than any previously known enzyme.",
        "target_summary": "A newly discovered enzyme breaks down PET plastic much faster than before.",
    },
    # ... more rows
]

# 2. Prompt: the starting instruction GEPA will iteratively rewrite
summary_prompt = "Summarize the following article in one sentence: {article}"

# 3. Evaluator: scores each generated summary with the summary_quality template
evaluator = Evaluator(
    eval_template="summary_quality",
    eval_model_name="turing_flash",
)

# 4. DataMapper: connects the dataset's keys to the eval's expected keys
data_mapper = BasicDataMapper(
    key_map={"input": "article", "output": "generated_output"}
)

# 5. Optimizer: GEPA evolves the prompt using a reflection model
optimizer = GEPAOptimizer(
    reflection_model="gpt-4-turbo",
    generator_model="gpt-4o-mini",
)

# 6. Run
result = optimizer.optimize(
    evaluator=evaluator,
    data_mapper=data_mapper,
    dataset=dataset,
    initial_prompts=[summary_prompt],
    max_metric_calls=150,
)

# 7. Read the result
print(f"Final score: {result.final_score:.4f}")
print(f"Best prompt:\n{result.best_generator.get_prompt_template()}")

for i, iteration in enumerate(result.history):
    print(f"Round {i + 1}: {iteration.average_score:.4f}")
```

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

### Install Docker, Compose, Git, and Colima on macOS

Source: https://docs.futureagi.com/docs/self-hosting/requirements

Install the required tools with Homebrew, then start Colima with 4 CPUs, 8 GB memory, and 64 GB disk.

```bash
brew install docker docker-compose colima git
colima start --cpu 4 --memory 8 --disk 64
```

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

### Full Python example: interact with MCP server

Source: https://docs.futureagi.com/docs/integrations/traceai/mcp

Complete Python example that initializes the trace provider, instruments OpenAI Agents and MCP, and runs an agent that interacts with a filesystem MCP server via npx. It requires npx to be installed and uses the @modelcontextprotocol/server-filesystem package.

```python
import asyncio
import os
import shutil

from agents import Agent, Runner
from agents.mcp import MCPServer, MCPServerStdio

from traceai_openai_agents import OpenAIAgentsInstrumentor
from traceai_mcp import MCPInstrumentor

from fi_instrumentation import register
from fi_instrumentation.fi_types import ProjectType

trace_provider = register(
    project_type=ProjectType.OBSERVE,
    project_name="mcp_project",
)

OpenAIAgentsInstrumentor().instrument(tracer_provider=trace_provider)
MCPInstrumentor().instrument(tracer_provider=trace_provider)

async def run(mcp_server: MCPServer):
    agent = Agent(
        name="Assistant",
        instructions="Use the tools to read the filesystem and answer questions based on those files.",
        mcp_servers=[mcp_server],
    )

    message = "Read the files and list them."
    print(f"Running: {message}")
    result = await Runner.run(starting_agent=agent, input=message)
    print(result.final_output)

async def main():
    current_dir = os.path.dirname(os.path.abspath(__file__))
    samples_dir = os.path.join(current_dir, "sample_files")

    async with MCPServerStdio(
        name="Filesystem Server, via npx",
        params={
            "command": "npx",
            "args": ["-y", "@modelcontextprotocol/server-filesystem", samples_dir],
        },
    ) as server:
        await run(server)

if __name__ == "__main__":
    if not shutil.which("npx"):
        raise RuntimeError("npx is not installed. Please install it with `npm install -g npx`.")

    asyncio.run(main())
```

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

### Install C# NuGet packages for distributed tracing

Source: https://docs.futureagi.com/docs/cookbook/quickstart/distributed-tracing

Install the required OpenTelemetry and DotNetEnv packages for the C# example.

```bash
dotnet add package OpenTelemetry OpenTelemetry.Exporter.OpenTelemetryProtocol OpenTelemetry.Instrumentation.AspNetCore OpenTelemetry.Instrumentation.Http DotNetEnv
```

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

### Basic configuration with OpenAI

Source: https://docs.futureagi.com/docs/command-center/deployment/self-hosted

Minimal configuration for getting started with OpenAI. Includes server host binding, OpenAI provider, authentication, and logging.

```yaml
server:
  port: 8080
  host: "0.0.0.0"

providers:
  openai:
    api_key: "${OPENAI_API_KEY}"
    api_format: "openai"
    models:
      - gpt-4o
      - gpt-4o-mini

auth:
  enabled: true
  keys:
    - name: "my-key"
      key: "sk-agentcc-my-key-here"

logging:
  level: info

```

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

### Python Quick Example: register() and OpenAIInstrumentor

Source: https://docs.futureagi.com/docs/sdk/tracing

Install the Python packages and set up OpenTelemetry tracing with the register() function and OpenAIInstrumentor. Requires FI_API_KEY and FI_SECRET_KEY in your environment.

```bash
pip install fi-instrumentation-otel traceAI-openai
```

```python
from fi_instrumentation import register
from fi_instrumentation.fi_types import ProjectType
from traceai_openai import OpenAIInstrumentor

# 1. Register the tracer provider
trace_provider = register(
    project_name="my-project",
    project_type=ProjectType.OBSERVE,
)

# 2. Instrument your framework
OpenAIInstrumentor().instrument(tracer_provider=trace_provider)

# 3. Use OpenAI as normal - all calls are now traced
import openai
client = openai.OpenAI()
response = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[{"role": "user", "content": "What is Python?"}],
}
```

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

### PromptWizardOptimizer optimization example

Source: https://docs.futureagi.com/future-agi/get-started/optimization/optimizers/promptwizard

Runs PromptWizardOptimizer on a small dataset of articles. Requires `pip install agent-opt`, `fi_api_key`/`fi_secret_key` (or `FI_API_KEY`/`FI_SECRET_KEY` env vars), and `OPENAI_API_KEY` for the `gpt-4o-mini` model. The `key_map` must match dataset keys; mismatches fail silently. Prints the final score and best prompt.

```python
from fi.opt.optimizers import PromptWizardOptimizer
from fi.opt.generators import LiteLLMGenerator
from fi.opt.datamappers import BasicDataMapper
from fi.opt.base.evaluator import Evaluator

# Dataset: a list of dicts, one per example. Keys must cover whatever the
# prompt template and key_map below reference, here just "article".
my_dataset = [
    {"article": "The James Webb Space Telescope has captured its clearest images yet of a distant exoplanet's atmosphere, revealing traces of carbon dioxide and methane."},
    {"article": "Researchers have discovered a new enzyme that breaks down PET plastic at room temperature, far faster than any previously known enzyme."},
]

# Teacher model used for critique and refinement; see teacher_generator in
# the table above. Your task prompt is passed to initial_prompts on
# optimize() below.
generator = LiteLLMGenerator(
    model="gpt-4o-mini",
    prompt_template="{prompt}"
)

# Evaluator that scores each candidate prompt.
# eval_template: see the built-in templates linked below
# eval_model_name: see the evaluator models linked below
evaluator = Evaluator(
    eval_template="summary_quality",
    eval_model_name="turing_flash",
    fi_api_key="your_key",
    fi_secret_key="your_secret"
)

# Maps generator output and dataset fields to what the evaluator expects.
# "article" must match a key in my_dataset; "generated_output" is filled
# in automatically by the optimizer, not a dataset field.
data_mapper = BasicDataMapper(
    key_map={"input": "article", "output": "generated_output"}
)

# mutate_rounds, refine_iterations, and beam_size here match the defaults
# in the table above and can be omitted; shown so they're easy to change.
optimizer = PromptWizardOptimizer(
    teacher_generator=generator,
    mutate_rounds=3,
    refine_iterations=2,
    beam_size=1
)

result = optimizer.optimize(
    evaluator=evaluator,
    data_mapper=data_mapper,
    dataset=my_dataset,
    # initial_prompts holds the starting prompt PromptWizard mutates and refines
    initial_prompts=["Summarize this article: {article}"]
)

# Read the optimized prompt and its score off the result
print(f"Final score: {result.final_score:.4f}")
print(f"Best prompt:\n{result.best_generator.get_prompt_template()}")
```

```text
Final score: 0.8214
Best prompt:
Summarize this article in 2-3 sentences, covering the main finding and its significance.
```

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

### LLM gateway config.yaml setup

Source: https://docs.futureagi.com/docs/self-hosting/configuration

Steps to set up the LLM gateway config.yaml: copy the example, edit providers and keys, set matching .env keys, mount the config in docker-compose, and restart the gateway. config.yaml is gitignored and treated as a secret.

```bash
# 1. Copy the example
cp futureagi/agentcc-gateway/config.example.yaml \
   futureagi/agentcc-gateway/config.yaml

# 2. Edit config.yaml — uncomment providers, set keys via ${VAR} interpolation
# 3. Set matching keys in .env (OPENAI_API_KEY, ANTHROPIC_API_KEY, etc.)

# 4. Point the gateway volume at your config.yaml (in docker-compose.yml)
#    volumes:
#      - ./futureagi/agentcc-gateway/config.yaml:/app/config.yaml:ro

# 5. Restart
docker compose up -d --force-recreate gateway
```

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

### Run the Python quickstart

Source: https://docs.futureagi.com/docs/get-started/send-your-first-trace

Execute the quickstart.py script to send a trace.

```bash
python quickstart.py
```

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

### Get word and segment timestamps with verbose_json

Source: https://docs.futureagi.com/docs/command-center/api/media

Requests word-level and segment-level timestamps by setting response_format to verbose_json and timestamp_granularities to ["word", "segment"]. The example iterates over transcription.words and prints each word with its start and end times.

```python
with open("recording.mp3", "rb") as f:
    transcription = client.audio.transcriptions.create(
        model="whisper-1",
        file=f,
        response_format="verbose_json",
        timestamp_granularities=["word", "segment"],
    )

for word in transcription.words:
    print(f"[{word.start:.2f}s - {word.end:.2f}s] {word.word}")
```

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

### Basic Setup: setup_tracing with console export

Source: https://docs.futureagi.com/docs/sdk/evals/otel

Basic setup that exports traces to the console by default. Requires only a service name.

```python
from fi.evals.otel import setup_tracing

setup_tracing(service_name="my-app")  # exports to console by default
```

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

### Manual trace propagation between TypeScript and Python services

Source: https://docs.futureagi.com/docs/observe/features/manual-tracing/advanced-tracing-examples

Service A (TypeScript) injects the active trace context into HTTP headers using propagation.inject and sends a request to Service B. Service B (Python) extracts that context from the incoming request headers with extract and starts a child span. The TypeScript example assumes Service B is on port 5002 and includes commented-out minimal OTel SDK setup for console output; the Python example assumes Service B runs on port 5001 and includes commented-out minimal OTel setup.

```typescript
import { trace, context, propagation, SpanStatusCode } from "@opentelemetry/api";
import { HttpTraceContextPropagator } from "@opentelemetry/core";
import fetch from "node-fetch"; // yarn add node-fetch @types/node-fetch

const tracer = trace.getTracer("my-service-a-tracer");

// It's common to set this globally once for an application.
propagation.setGlobalPropagator(new HttpTraceContextPropagator());

async function makeRequestToServiceB(): Promise<string> {
    return await tracer.startActiveSpan("typescript_llm_service_a", async (span) => {
        const headers: Record<string, string> = {};
        propagation.inject(context.active(), headers);

        try {
            const response = await fetch("http://localhost:5002/ts-endpoint", { headers }); // Assuming TS Service B on 5002
            if (!response.ok) {
                span.setStatus({ code: SpanStatusCode.ERROR, message: `HTTP error! status: ${response.status}` });
                throw new Error(`HTTP error! status: ${response.status}`);
            }
            const data = await response.text();
            span.setStatus({ code: SpanStatusCode.OK });
            return data;
        } catch (error) {
            span.recordException(error as Error);
            span.setStatus({ code: SpanStatusCode.ERROR, message: (error as Error).message });
            throw error;
        } finally {
            span.end();
        }
    });
}

// Example usage (ensure Service B is running and OTel SDK is configured):
// async function main() {
//     // Minimal OTel SDK setup for console output
//     const { NodeTracerProvider } = await import('@opentelemetry/sdk-trace-node');
//     const { ConsoleSpanExporter, SimpleSpanProcessor } = await import('@opentelemetry/sdk-trace-base');
//     const provider = new NodeTracerProvider();
//     provider.addSpanProcessor(new SimpleSpanProcessor(new ConsoleSpanExporter()));
//     provider.register();
//     try {
//         const response = await makeRequestToServiceB();
//         console.log("Response from Service B:", response);
//     } catch (err) {
//         console.error("Error making request:", err);
//     }
// }
// main();
```

```python
from flask import Flask, request
from opentelemetry import trace
from opentelemetry.propagate import inject, extract
# Minimal OTel setup for console output if not already configured globally
# from opentelemetry.sdk.trace import TracerProvider
# from opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor
# trace.set_tracer_provider(TracerProvider())
# trace.get_tracer_provider().add_span_processor(SimpleSpanProcessor(ConsoleSpanExporter()))

app = Flask(__name__)
tracer = trace.get_tracer("my-service-b-tracer") # Corrected tracer name from __name__ for clarity

@app.route("/endpoint")
def endpoint():
    # Extract the context from incoming request
    context_from_propagator = extract(carrier=dict(request.headers))

    # Create a new span as child
    with tracer.start_as_current_span("python_service_b_processing", context=context_from_propagator) as span:
        span.add_event("Received request in Python Service B")
        # ... do some processing ...
        return "Hello from Python Service B"

# if __name__ == "__main__":
#     app.run(port=5001) # Assuming Python Service B runs on 5001
```

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

### Install SDK and initialize Protect

Source: https://docs.futureagi.com/docs/protect/features/run-protect

Install the SDK and initialize the Protect client. Protect reads FI_API_KEY and FI_SECRET_KEY from your environment; generate these on the API Keys page if you don't have them yet.

```bash
pip install ai-evaluation
```

```python
from fi.evals import Protect

protector = Protect()
```

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

### Get Tracer and Start Tool Call Span (JavaScript)

Source: https://docs.futureagi.com/docs/sdk/tracing/get-current-span-context

Get a tracer from a registered tracer provider and start an active span for a tool call. Handles errors by recording exceptions and setting error status.

```javascript
const { trace, context, SpanStatusCode } = require("@opentelemetry/api");
const { AsyncLocalStorageContextManager } = require("@opentelemetry/context-async-hooks");
const { register } = require("@traceai/fi-core");
const { ProjectType } = require("@traceai/fi-core");
const { registerInstrumentations } = require("@opentelemetry/instrumentation");

const tracerProvider = register({
    projectName: "manual-instrumentation-example",
    projectType: ProjectType.OBSERVE,
    sessionName: "manual-instrumentation-example-session"
});

const tracer = tracerProvider.getTracer("manual-instrumentation-example");

tracer.startActiveSpan("HandleFunctionCall", {
    attributes: {
        "fi.span.kind": "tool",
        "tool.call.function.name": functionCallName,
        "tool.call.function.arguments_json": JSON.stringify(receivedArguments),
        "input.value": functionCallName
    }
}, (span) => {
    try {
        span.setStatus({ code: SpanStatusCode.OK });
    } catch (error) {
        span.recordException(error);
        span.setStatus({ code: SpanStatusCode.ERROR, message: error.message });
        throw error;
    } finally {
        span.end();
    }
});
```

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

### Get Tracer and Start Tool Call Span (Python)

Source: https://docs.futureagi.com/docs/sdk/tracing/get-current-span-context

Get a tracer using trace.get_tracer(__name__) and start a new span with tool-specific attributes. Assumes FiSpanKindValues, SpanAttributes, ToolCallAttributes, function_call_name, and arguments are defined externally.

```python
from opentelemetry import trace
# Assuming FiSpanKindValues, SpanAttributes, ToolCallAttributes,
# function_call_name, and arguments variables are defined externally.

tracer = trace.get_tracer(__name__)

# Start a new span for the tool function handling
with tracer.start_as_current_span("HandleFunctionCall", attributes={
    SpanAttributes.GEN_AI_SPAN_KIND: FiSpanKindValues.TOOL.value,
    ToolCallAttributes.TOOL_CALL_FUNCTION_NAME: function_call_name,
    ToolCallAttributes.TOOL_CALL_FUNCTION_ARGUMENTS_JSON: str(arguments),
    SpanAttributes.INPUT_VALUE: function_call_name
}) as span:
    pass
```

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

### Set up ChromaFeedbackStore

Source: https://docs.futureagi.com/docs/sdk/evals/feedback

Install the feedback extra and create a ChromaFeedbackStore for production. It persists to disk and uses vector search for semantic retrieval. The store defaults to local disk.

```bash
pip install ai-evaluation[feedback]
```

```python
from fi.evals.feedback import ChromaFeedbackStore

store = ChromaFeedbackStore()  # defaults to local disk
```

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

### Clone and run the installer

Source: https://docs.futureagi.com/docs/self-hosting/installation

Clones the repository and runs the installer. On Windows, run bin\install.ps1 instead. The stack boots fine against an empty .env, so defaults are acceptable for a local trial. By default the installer brings up 13 services; add --full to include the PeerDB CDC stack (23 services).

```bash
git clone https://github.com/future-agi/future-agi.git
cd future-agi
./bin/install
```

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

### Run the JS/TS quickstart

Source: https://docs.futureagi.com/docs/get-started/send-your-first-trace

Execute the quickstart.ts script using npx tsx to send a trace.

```bash
npx tsx quickstart.ts
```

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

### Set up tracer for manual spans with FITracer

Source: https://docs.futureagi.com/docs/observe/features/manual-tracing/set-up-tracing

Set up a tracer for manual spans with FITracer. The Python example sets the tracer provider and gets a tracer. The TypeScript example activates a context manager, registers a provider, and gets a tracer.

```python
from opentelemetry import trace

trace.set_tracer_provider(trace_provider)
tracer = trace.get_tracer(__name__)
```

```javascript
const { trace, context } = require("@opentelemetry/api");
const { AsyncLocalStorageContextManager } = require("@opentelemetry/context-async-hooks");
const { register } = require("@traceai/fi-core");
const { ProjectType } = require("@traceai/fi-core");
const { registerInstrumentations } = require("@opentelemetry/instrumentation");

// Activate a context manager for consistent context propagation
context.setGlobalContextManager(new AsyncLocalStorageContextManager());

// Initialize and get a tracer using our register function
const traceProvider = register({
    projectType: ProjectType.OBSERVE,
    projectName: "FUTURE_AGI"
});

const tracer = traceProvider.getTracer("manual-instrumentation-example");
```

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

### Get Tracer and Start Tool Call Span (Python/JavaScript)

Source: https://docs.futureagi.com/docs/observe/features/manual-tracing/get-current-span-context

Get a tracer and start a new span for tool function handling with custom attributes. Python uses trace.get_tracer(__name__) and start_as_current_span; JavaScript uses tracerProvider.getTracer() and startActiveSpan, with error handling and span status.

```python
from opentelemetry import trace
# Assuming FiSpanKindValues, SpanAttributes, ToolCallAttributes,
# function_call_name, and arguments variables are defined externally.

tracer = trace.get_tracer(__name__)

# Start a new span for the tool function handling
with tracer.start_as_current_span("HandleFunctionCall", attributes={
    SpanAttributes.GEN_AI_SPAN_KIND: FiSpanKindValues.TOOL.value,
    ToolCallAttributes.TOOL_CALL_FUNCTION_NAME: function_call_name,
    ToolCallAttributes.TOOL_CALL_FUNCTION_ARGUMENTS_JSON: str(arguments),
    SpanAttributes.INPUT_VALUE: function_call_name
}) as span:
    pass
```

```javascript
const { trace, context, SpanStatusCode } = require("@opentelemetry/api");
const { AsyncLocalStorageContextManager } = require("@opentelemetry/context-async-hooks");
const { register } = require("@traceai/fi-core");
const { ProjectType } = require("@traceai/fi-core");
const { registerInstrumentations } = require("@opentelemetry/instrumentation");

const tracerProvider = register({
    projectName: "manual-instrumentation-example",
    projectType: ProjectType.OBSERVE,
    sessionName: "manual-instrumentation-example-session"
});

const tracer = tracerProvider.getTracer("manual-instrumentation-example");

tracer.startActiveSpan("HandleFunctionCall", {
    attributes: {
        "fi.span.kind": "tool",
        "tool.call.function.name": functionCallName,
        "tool.call.function.arguments_json": JSON.stringify(receivedArguments),
        "input.value": functionCallName
    }
}, (span) => {
    try {
        span.setStatus({ code: SpanStatusCode.OK });
    } catch (error) {
        span.recordException(error);
        span.setStatus({ code: SpanStatusCode.ERROR, message: error.message });
        throw error;
    } finally {
        span.end();
    }
});
```

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

### Create a Knowledge Base via SDK

Source: https://docs.futureagi.com/docs/cookbook/quickstart/knowledge-base

Creates a Knowledge Base named 'product-docs' with three files. Requires FI_API_KEY and FI_SECRET_KEY environment variables. Prints the KB name after creation.

```python
import os
from fi.kb import KnowledgeBase

kb_client = KnowledgeBase(
    fi_api_key=os.environ["FI_API_KEY"],
    fi_secret_key=os.environ["FI_SECRET_KEY"],
)

kb_client.create_kb(
    name="product-docs",
    file_paths=[
        "./docs/return-policy.txt",
        "./docs/shipping-info.txt",
        "./docs/product-catalog.pdf",
    ],
)

print(f"KB created: {kb_client.kb.name}")
```

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

### Install Agent Command Center SDK

Source: https://docs.futureagi.com/docs/command-center/quickstart

Install the agentcc package via pip. This is a prerequisite for using the Agent Command Center SDK in the quickstart.

```bash
pip install agentcc
```

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

### Run the quickstart script

Source: https://docs.futureagi.com/docs/quickstart

Run the quickstart script. Python uses python quickstart.py; JS/TS uses npx tsx quickstart.ts. The model's reply appears in the terminal and the trace is sent to Future AGI in the background.

```bash
python quickstart.py
```

```bash
npx tsx quickstart.ts
```

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

### Install dependencies for LiveKit Agents and Future AGI instrumentation

Source: https://docs.futureagi.com/docs/cookbook/quickstart/instrument-and-verify-voice

Install the required packages: livekit-agents with OpenAI extras, fi-instrumentation-otel, and traceai-livekit. This is the prerequisite for running the example.

```bash
pip install "livekit-agents[openai]" fi-instrumentation-otel traceai-livekit
```

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

### Install and configure environment

Source: https://docs.futureagi.com/docs/cookbook/quickstart/protect-guardrails

Install the required packages and set environment variables for API keys before using Protect.

```bash
pip install ai-evaluation openai
```

```bash
export FI_API_KEY="your-api-key"
export FI_SECRET_KEY="your-secret-key"
export OPENAI_API_KEY="your-openai-api-key"
```

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

### Install dependencies for chat simulation

Source: https://docs.futureagi.com/cookbook/cookbook18/chat-simulation-with-fix-my-agent

Install the required Python packages and set the necessary environment variables including FI_API_KEY, FI_SECRET_KEY, and GEMINI_API_KEY. This setup is required before running the simulation.

```shell
pip install agent-simulate litellm futureagi
```

```shell
export FI_API_KEY="your-api-key"
export FI_SECRET_KEY="your-secret-key"
export GEMINI_API_KEY="your-llm-provider-key"

```

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

### Install Docker, Compose, and Git on Linux (apt)

Source: https://docs.futureagi.com/docs/self-hosting/requirements

Install the tools with apt, enable the Docker daemon, and add the current user to the docker group. Log out and back in for the group change to take effect.

```bash
sudo apt-get install -y docker.io docker-compose-v2 git
sudo systemctl enable --now docker
sudo usermod -aG docker $USER   # log out and back in
```

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

### Create config.yaml for Docker quick start

Source: https://docs.futureagi.com/docs/command-center/deployment/self-hosted

Save this as config.yaml for the Docker quick start. It configures the server port, an OpenAI provider, authentication with a single key, and logging level.

```yaml
server:
  port: 8080

providers:
  openai:
    api_key: "${OPENAI_API_KEY}"
    api_format: "openai"
    models:
      - gpt-4o
      - gpt-4o-mini

auth:
  enabled: true
  keys:
    - name: "my-key"
      key: "sk-agentcc-my-key-here"

logging:
  level: info

```

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

### Random Search Optimizer Usage Example

Source: https://docs.futureagi.com/docs/optimization/reference/optimizers/random-search

Complete example of using RandomSearchOptimizer with LiteLLMGenerator, Evaluator, and BasicDataMapper. Requires pip install agent-opt and API keys. The example shows how to set up the generator, evaluator, data mapper, dataset, and run the optimization.

```python
from fi.opt.optimizers import RandomSearchOptimizer
from fi.opt.generators import LiteLLMGenerator
from fi.opt.datamappers import BasicDataMapper
from fi.opt.base.evaluator import Evaluator

# Generator holding the starting prompt
generator = LiteLLMGenerator(
    model="gpt-4o-mini",
    prompt_template="Summarize this article: {article}"
)

# Evaluator that scores each variation
evaluator = Evaluator(
    eval_template="summary_quality",
    eval_model_name="turing_flash",
    fi_api_key="your_key",
    fi_secret_key="your_secret"
)

# Maps generator output and dataset fields to what the evaluator expects.
# "generated_output" is the generator's fixed output key; "article" is
# the dataset field from this example and should match your own data.
data_mapper = BasicDataMapper(
    key_map={"input": "article", "output": "generated_output"}
)

# Dataset: a plain list of dicts, one per example the optimizer scores the prompt against
my_dataset = [
    {"article": "The James Webb Space Telescope has captured its clearest images yet of a distant exoplanet's atmosphere, revealing traces of carbon dioxide and methane."},
    {"article": "Researchers have discovered a new enzyme that breaks down PET plastic at room temperature, far faster than any previously known enzyme."},
]

optimizer = RandomSearchOptimizer(
    generator=generator,
    num_variations=3
)

result = optimizer.optimize(
    evaluator=evaluator,
    data_mapper=data_mapper,
    dataset=my_dataset
)

print(f"Final score: {result.final_score:.4f}")
print(f"Best prompt:\n{result.best_generator.get_prompt_template()}")
```

```text
Final score: 0.8532
Best prompt:
Summarize this article in 2-3 sentences, covering the main finding and its significance.
```

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

### Install traceAI-instructor and instructor

Source: https://docs.futureagi.com/docs/integrations/traceai/instructor

Install the required packages using pip.

```bash
pip install traceAI-instructor instructor
```

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

### Create a custom tracing decorator with opentelemetry Python

Source: https://docs.futureagi.com/docs/observe/features/manual-tracing/advanced-tracing-examples

Defines a reusable decorator that starts a span before the function call, records arguments and return value as span attributes, and ends the span without modifying the function body. Includes an example usage with span_kind="LLM" and additional_attributes, plus commented-out minimal OTel SDK setup for console output.

```python
from opentelemetry import trace
import functools # Import functools for functools.wraps

def trace_function(span_kind=None, additional_attributes=None):
    def decorator(func):
        @functools.wraps(func) # Preserve function metadata
        def wrapper(*args, **kwargs):
            tracer = trace.get_tracer(__name__, "0.1.0") # Added version for tracer
            with tracer.start_as_current_span(func.__name__) as span:
                if span_kind:
                    span.set_attribute("fi.span.kind", span_kind)

                # Securely convert args and kwargs to string for attributes
                try:
                    span.set_attribute("function.arguments", str(args))
                    span.set_attribute("function.keyword_arguments", str(kwargs))
                except Exception as e:
                    span.set_attribute("function.arguments.error", str(e))

                if additional_attributes:
                    for key, value in additional_attributes.items():
                        span.set_attribute(key, value)

                result = func(*args, **kwargs)
                try:
                    span.set_attribute("function.return_value", str(result))
                except Exception as e:
                    span.set_attribute("function.return_value.error", str(e))
                return result
        return wrapper
    return decorator

# Example Implementation
@trace_function(span_kind="LLM", additional_attributes={"llm.model_name": "gpt-4o"})
def process_text(text: str, verbose: bool = False):
    if verbose:
        print(f"Processing text: {text}")
    return text.upper()

# if __name__ == "__main__":
#     # Minimal OTel SDK setup for console output
#     from opentelemetry.sdk.trace import TracerProvider
#     from opentelemetry.sdk.trace.export import ConsoleSpanExporter, SimpleSpanProcessor
#     trace.set_tracer_provider(TracerProvider())
#     trace.get_tracer_provider().add_span_processor(SimpleSpanProcessor(ConsoleSpanExporter()))
#     print(process_text("hello world", verbose=True))
```

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

### Install packages and set API keys

Source: https://docs.futureagi.com/cookbook/optimization/eval-metrics-for-optimization

Install the required packages and set the environment variables needed for the tutorial. The API keys are used by the platform evaluator and the local LLM-as-a-judge.

```bash
pip install agent-opt ai-evaluation litellm
```

```bash
export FI_API_KEY="your-api-key"
export FI_SECRET_KEY="your-secret-key"
export OPENAI_API_KEY="your-openai-api-key"
```

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

### Set FI_API_KEY and FI_SECRET_KEY environment variables

Source: https://docs.futureagi.com/docs/observe/features/manual-tracing/set-up-tracing

Set API credentials as environment variables. The Python example uses os.environ, the TypeScript example uses process.env. Get your keys from the dashboard.

```python
import os

os.environ["FI_API_KEY"] = "your-futureagi-api-key"
os.environ["FI_SECRET_KEY"] = "your-futureagi-secret-key"
```

```javascript
process.env.FI_API_KEY = FI_API_KEY;
process.env.FI_SECRET_KEY = FI_SECRET_KEY;
```

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

### Quick Example: Bayesian Search Optimizer

Source: https://docs.futureagi.com/docs/sdk/optimization

Core example showing how to set up and run a Bayesian search optimization using BasicDataMapper, Evaluator, BLEUScore, and LiteLLMGenerator. It requires the agent-opt package and Python 3.10+.

```python
from fi.opt.generators import LiteLLMGenerator
from fi.opt.optimizers import BayesianSearchOptimizer
from fi.opt.datamappers import BasicDataMapper
from fi.opt.base.evaluator import Evaluator
from fi.evals.metrics import BLEUScore

# 1. Your dataset
dataset = [
    {"context": "Paris is the capital of France", "question": "What is the capital of France?", "answer": "Paris"},
    {"context": "Tokyo is the capital of Japan", "question": "What is the capital of Japan?", "answer": "Tokyo"},
]

# 2. Evaluator — how to score each output
metric = BLEUScore()
evaluator = Evaluator(metric)

# 3. Data mapper — connects optimizer output to evaluator inputs
data_mapper = BasicDataMapper(
    key_map={"response": "generated_output", "expected_response": "answer"}
)

# 4. Optimizer
optimizer = BayesianSearchOptimizer(
    inference_model_name="gpt-4o-mini",
    teacher_model_name="gpt-4o",
    n_trials=10,
)

# 5. Run
initial_prompt = "Given the context: {context}, answer the question: {question}"
result = optimizer.optimize(
    evaluator=evaluator,
    data_mapper=data_mapper,
    dataset=dataset,
    initial_prompts=[initial_prompt],
)

print(f"Best Score: {result.final_score:.4f}")
print(f"Best Prompt: {result.best_generator.get_prompt_template()}")
```

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

### Install dependencies

Source: https://docs.futureagi.com/docs/cookbook/meeting-summarization

Install the required Python packages for the tutorial.

```bash
pip install ai-evaluation bert-score pandas tabulate
```

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

### Install OpenAI SDK and Set API Key

Source: https://docs.futureagi.com/docs/cookbook/command-center/semantic-caching

Install the OpenAI SDK and set the Agent Command Center API key as an environment variable. The key must start with `sk-agentcc-`.

```bash
pip install openai
```

```bash
export AGENTCC_API_KEY="sk-agentcc-your-key"
```

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

### Copy the production environment example file

Source: https://docs.futureagi.com/docs/self-hosting/production/checklist

Copy the shipped example environment file to deploy/.env.production. These values go in deploy/.env.production, not the root .env.

```bash
cp deploy/.env.production.example deploy/.env.production
```

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

### Example usage of test case classes

Source: https://docs.futureagi.com/docs/sdk/testcase

Shows how to import and instantiate TestCase, LLMTestCase, ConversationalTestCase, and MLLMTestCase with example values. Use this as a starting point for creating test cases in your evaluation workflows.

```python
from fi.testcase import TestCase, LLMTestCase, ConversationalTestCase, MLLMTestCase

# Simple test case
tc = TestCase(input="What is the capital of France?", output="Paris")

# LLM test case
llm_tc = LLMTestCase(query="Who wrote 1984?", response="George Orwell")

# Conversational test case
conv_tc = ConversationalTestCase(messages=[llm_tc])

# Multimodal test case
mllm_tc = MLLMTestCase(
    input="Describe this image.",
    image_url="path/to/image.jpg"
)
```

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

### Set up FITracer in Python and JavaScript

Source: https://docs.futureagi.com/docs/observe/features/manual-tracing/instrument-with-traceai-helpers

Set up your tracer by registering your project and initializing a FITracer from the returned provider. The Python example uses ProjectType.EXPERIMENT and the JavaScript example uses ProjectType.OBSERVE.

```python
from fi_instrumentation import register, FITracer
from fi_instrumentation.fi_types import ProjectType

# Setup OTel via our register function
trace_provider = register(
    project_type=ProjectType.EXPERIMENT,
    project_name="FUTURE_AGI",
    project_version_name="openai-exp",
)

tracer = FITracer(trace_provider.get_tracer(__name__))
```

```javascript
const { trace, context, SpanStatusCode, propagation } = require("@opentelemetry/api");
const { AsyncLocalStorageContextManager } = require("@opentelemetry/context-async-hooks");
const { register, ProjectType } = require("@traceai/fi-core");
const { registerInstrumentations } = require("@opentelemetry/instrumentation");
const { suppressTracing } = require("@opentelemetry/core");

context.setGlobalContextManager(new AsyncLocalStorageContextManager());

const tracerProvider = register({
    projectName: "manual-instrumentation-example",
    projectType: ProjectType.OBSERVE,
    sessionName: "manual-instrumentation-example-session"
});

const tracer = tracerProvider.getTracer("manual-instrumentation-example");
```

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

### Set up environment: register tracer and initialize Evaluator

Source: https://docs.futureagi.com/docs/sdk/tracing/in-line-evals

Set up the environment by registering a tracer provider and initializing the Evaluator with your FI_API_KEY and FI_SECRET_KEY credentials. Requires the fi_instrumentation and fi.evals packages.

```python
import os
import openai
from fi_instrumentation import register, FITracer
from fi_instrumentation.fi_types import (
    ProjectType
)
from fi.evals import Evaluator


# Register the tracer
trace_provider = register(
    project_type=ProjectType.OBSERVE,
    project_name="YOUR_PROJECT_NAME",
    set_global_tracer_provider=True
)

# Initialize the Evaluator
evaluator = Evaluator(fi_api_key=os.getenv("FI_API_KEY"), fi_secret_key=os.getenv("FI_SECRET_KEY"))

client = openai.OpenAI()
tracer = FITracer(trace_provider.get_tracer(__name__))
```

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

### Run Dead Air Detection with evaluate()

Source: https://docs.futureagi.com/docs/evaluation/builtin/dead-air-detection

Call evaluate() with the template name "dead_air_detection" and the required input_audio. The Python example prints the score and reason; the TypeScript example logs the result. Install the SDK and set FI_API_KEY / FI_SECRET_KEY before running.

```python
from fi.evals import evaluate

result = evaluate(
    "dead_air_detection",
    input_audio="https://storage.example.com/calls/call_4471.wav",
)

print(result.score)
print(result.reason)
```

```typescript
import { evaluate } from "@future-agi/ai-evaluation";

const result = await evaluate(
  "dead_air_detection",
  {
    input_audio: "https://storage.example.com/calls/call_4471.wav",
  }
);

console.log(result);
```