Operator Manual

import os

# Secrets from your Vault are available as env vars
OPENAI_API_KEY = os.getenv("OPENAI_API_KEY")
ANTHROPIC_API_KEY = os.getenv("ANTHROPIC_API_KEY")

# Use them in your agent
from openai import OpenAI
client = OpenAI(api_key=OPENAI_API_KEY)

import os
import psycopg2

# AgentRealm injects this automatically - do not hardcode!
DATABASE_URL = os.getenv("DATABASE_URL")

# Connect to your agent's dedicated database
conn = psycopg2.connect(DATABASE_URL)

# Store conversation history, embeddings, state, etc.
cursor = conn.cursor()
cursor.execute("""
    CREATE TABLE IF NOT EXISTS memory (
        id SERIAL PRIMARY KEY,
        timestamp TIMESTAMPTZ DEFAULT NOW(),
        content JSONB
    )
""")

import os
from langchain.memory import PostgresChatMessageHistory
from langchain.chains import ConversationChain

DATABASE_URL = os.getenv("DATABASE_URL")

# Persistent conversation memory
history = PostgresChatMessageHistory(
    connection_string=DATABASE_URL,
    session_id="user_123"
)

# Your agent now remembers everything
chain = ConversationChain(memory=history, ...)

import os
import psycopg2
from openai import OpenAI

DATABASE_URL = os.getenv("DATABASE_URL")
# Also available: VECTOR_STORE_URL (alias for clarity)

conn = psycopg2.connect(DATABASE_URL)
cursor = conn.cursor()

# pgvector is pre-installed - just use it!
cursor.execute("""
    CREATE TABLE IF NOT EXISTS agent_memory (
        id SERIAL PRIMARY KEY,
        content TEXT,
        embedding vector(1536),  -- OpenAI ada-002 dimensions
        metadata JSONB,
        created_at TIMESTAMPTZ DEFAULT NOW()
    )
""")

# Create HNSW index for fast similarity search
cursor.execute("""
    CREATE INDEX IF NOT EXISTS memory_embedding_idx 
    ON agent_memory USING hnsw (embedding vector_cosine_ops)
""")

# Store a memory with embedding
def remember(content: str, metadata: dict = None):
    client = OpenAI()
    response = client.embeddings.create(
        model="text-embedding-ada-002",
        input=content
    )
    embedding = response.data[0].embedding
    
    cursor.execute(
        "INSERT INTO agent_memory (content, embedding, metadata) VALUES (%s, %s, %s)",
        (content, embedding, json.dumps(metadata or {}))
    )
    conn.commit()

# Retrieve similar memories
def recall(query: str, limit: int = 5):
    client = OpenAI()
    response = client.embeddings.create(
        model="text-embedding-ada-002",
        input=query
    )
    query_embedding = response.data[0].embedding
    
    cursor.execute("""
        SELECT content, metadata, 1 - (embedding <=> %s::vector) as similarity
        FROM agent_memory
        ORDER BY embedding <=> %s::vector
        LIMIT %s
    """, (query_embedding, query_embedding, limit))
    
    return cursor.fetchall()

-- Add this to your database initialization
CREATE TABLE IF NOT EXISTS agent_traces (
    id SERIAL PRIMARY KEY,
    session_id VARCHAR(255) NOT NULL,
    step_type VARCHAR(50) NOT NULL,  -- thinking, tool_call, llm_call, error
    content JSONB NOT NULL,          -- {"input": "...", "output": "..."}
    duration_ms INTEGER,
    tokens_used INTEGER,
    model VARCHAR(100),
    created_at TIMESTAMP DEFAULT NOW()
);

CREATE INDEX IF NOT EXISTS idx_traces_session ON agent_traces(session_id);
CREATE INDEX IF NOT EXISTS idx_traces_created ON agent_traces(created_at);

import os
import psycopg2
import json
import uuid

DATABASE_URL = os.getenv("DATABASE_URL")
conn = psycopg2.connect(DATABASE_URL)

class AgentTracer:
    def __init__(self, session_id: str = None):
        self.session_id = session_id or str(uuid.uuid4())
    
    def log_step(self, step_type: str, input_data: str, output_data: str, 
                 model: str = None, tokens: int = 0, duration_ms: int = 0):
        """Log a reasoning step to the traces table"""
        cursor = conn.cursor()
        cursor.execute("""
            INSERT INTO agent_traces 
            (session_id, step_type, content, model, tokens_used, duration_ms)
            VALUES (%s, %s, %s, %s, %s, %s)
        """, (
            self.session_id, step_type,
            json.dumps({"input": input_data, "output": output_data}),
            model, tokens, duration_ms
        ))
        conn.commit()

# Usage in your agent
tracer = AgentTracer()

# Log thinking
tracer.log_step(
    step_type="thinking",
    input_data="User asked: What's the weather in Berlin?",
    output_data="I need to call a weather API to answer this question"
)

# Log tool call
tracer.log_step(
    step_type="tool_call",
    input_data="get_weather(location='Berlin')",
    output_data='{"temp": 15, "condition": "cloudy"}',
    duration_ms=230
)

import os

# These are automatically injected from your Vault
# No need to manage .env files or secret mounting

OPENAI_API_KEY = os.getenv("OPENAI_API_KEY")       # From Vault
ANTHROPIC_API_KEY = os.getenv("ANTHROPIC_API_KEY") # From Vault
STRIPE_SECRET_KEY = os.getenv("STRIPE_SECRET_KEY") # From Vault

# Custom agent secrets (prefix with AGENT_)
MY_CUSTOM_TOKEN = os.getenv("AGENT_MY_CUSTOM_TOKEN")  # From Vault

# Format: minute hour day month weekday

* * * * *       # Every minute
*/5 * * * *     # Every 5 minutes
0 * * * *       # Every hour (at minute 0)
0 9 * * *       # Daily at 9:00 AM
0 0 * * 0       # Weekly on Sunday at midnight
0 0 1 * *       # Monthly on the 1st at midnight

curl -X POST http://localhost:8080/api/daily-summary

# Automatically injected by AgentRealm
PORT=8080              # Your agent MUST listen on this port
DATABASE_URL=postgres://...  # Your dedicated database

# From your Secret Vault (encrypted at rest)
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...

# Custom env vars from Dashboard
MY_CUSTOM_VAR=value

my-agent/
├── main.py           # Entry point (must exist)
├── requirements.txt  # Python dependencies
└── README.md         # Optional

my-agent/
├── index.js          # Entry point
├── package.json      # Node dependencies + start script
└── README.md         # Optional

# Custom Dockerfile - full control
FROM python:3-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .

# AgentRealm injects PORT=8080
CMD ["python", "main.py"]

FROM python:3-slim

WORKDIR /app

# Install dependencies
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Copy source code
COPY . .

# AgentRealm injects PORT=8080
EXPOSE 8080

# Start your agent
CMD ["python", "main.py"]

import os
from flask import Flask

app = Flask(__name__)

@app.route("/")
def health():
    return {"status": "online", "agent": "my-agent-v1"}

@app.route("/chat", methods=["POST"])
def chat():
    # Your agent logic here
    return {"response": "Hello from AgentRealm!"}

if __name__ == "__main__":
    port = int(os.getenv("PORT", 8080))
    app.run(host="0.0.0.0", port=port)