Veris AI Python SDK

Retired. veris-ai mocked tool calls for the Veris simulation platform, which retired on 2026-10-15 and is replaced by Veris Bench. Environment images and data are kept until 2026-11-14, then deleted. Questions or data requests: hello@veris.ai. Details: https://docs.veris.ai/deprecation

Tool mocking and MCP server integration for AI agent simulation. For more information visit veris.ai.

Quick Start

Install the SDK:

uv add veris-ai --extra fastapi --extra agents

Minimal Example

from fastapi import FastAPI
from pydantic import BaseModel
from agents import Agent, function_tool, Runner
from veris_ai import veris

app = FastAPI()

# 1. Define tools with @veris.mock() - returns simulated responses during simulation
@function_tool
@veris.mock()
def get_user(user_id: str) -> dict:
    """Get user information."""
    return db.get_user(user_id)

# 2. Create an agent with the tools
agent = Agent(name="Assistant", model="gpt-4", tools=[get_user])

# 3. Expose an endpoint that invokes the agent
class ChatRequest(BaseModel):
    message: str

@app.post("/chat")
async def chat(req: ChatRequest):
    result = await Runner.run(agent, req.message)
    return {"response": result.final_output}

# 4. Set up the MCP server
veris.set_fastapi_mcp(fastapi=app)
veris.fastapi_mcp.mount_http()

Your FastAPI app now exposes an MCP server at /mcp. During Veris simulations, decorated tools return simulated responses; in production, they execute normally.

Installation

# Base package
uv add veris-ai

# With FastAPI MCP support
uv add veris-ai --extra fastapi

# With OpenAI agents support
uv add veris-ai --extra agents

# All extras
uv add veris-ai --extra dev --extra fastapi --extra agents

Configuration

MCP Server

The SDK wraps fastapi-mcp to expose your FastAPI endpoints as MCP tools with automatic session handling.

Basic Setup

from fastapi import FastAPI
from veris_ai import veris

app = FastAPI()

# Minimal setup
veris.set_fastapi_mcp(fastapi=app)
veris.fastapi_mcp.mount_http()

Configuration Options

veris.set_fastapi_mcp(
    fastapi=app,

    # Server metadata
    name="My API Server",
    description="API for user management",

    # Filter which endpoints become MCP tools
    include_operations=["get_user", "update_user"],  # Only these operation IDs
    # OR
    exclude_operations=["internal_cleanup"],          # All except these
)

Filtering Rules:

• Cannot use both include_operations and exclude_operations

Accessing the MCP Server

The MCP server is available at /mcp on your FastAPI base URL:

• Local: http://localhost:8000/mcp
• Production: https://your-api.com/mcp

Prompt Sync

Register your agent's system prompt so Veris can optimize it across simulation runs.

Single Agent

from veris_ai import veris

veris.register_prompt("You are a helpful customer support agent...")

# In your agent's instruction function:
def get_instructions(ctx, agent):
    return veris.get_prompt() or default_prompt

Multi-Agent

veris.register_prompt("Handle billing inquiries...", agent_name="billing_agent")
veris.register_prompt("Handle tech support...", agent_name="tech_agent")

# Retrieve per-agent
billing_prompt = veris.get_prompt(agent_name="billing_agent")
tech_prompt = veris.get_prompt(agent_name="tech_agent")

get_prompt() returns the optimized prompt from Veris if available, otherwise the original registered prompt.

Tool Mocking

Decorators control function behavior during simulations.

@veris.mock()

Returns simulated responses when a session is active:

from veris_ai import veris

@veris.mock()
async def get_account_balance(account_id: str) -> dict:
    """Get account balance."""
    return await bank_api.get_balance(account_id)

Options:

@veris.mock(
    mode="tool",           # "tool" (default) or "function"
    expects_response=True, # Whether to wait for mock response
    cache_response=False,  # Cache responses for identical calls
)

@veris.spy()

Executes the original function and logs the call/response:

@veris.spy()
async def process_payment(amount: float, recipient: str) -> dict:
    """Process a payment - logs but executes normally."""
    return await payment_api.send(amount, recipient)

@veris.stub()

Returns a fixed value during simulations:

@veris.stub(return_value={"status": "success", "id": "test-123"})
async def create_order(items: list) -> dict:
    """Create order - returns stub in simulation."""
    return await order_api.create(items)

Decorator Behavior Summary

Simulation Context

When building custom agents (not using the OpenAI Agents SDK), wrap your agent execution in a context manager to activate simulation mode:

from fastapi import FastAPI
from veris_ai import veris

app = FastAPI()

@veris.mock()
async def search_web(query: str) -> str:
    """Search the web."""
    return await search_api.query(query)

@app.post("/chat")
async def chat(message: str):
    # Wrap agent execution to enable tool mocking during simulations
    async with veris.target_context_async("my_agent"):
        result = await my_custom_agent.run(message)
    return {"response": result}

veris.set_fastapi_mcp(fastapi=app)
veris.fastapi_mcp.mount_http()

A sync version is also available:

with veris.target_context("my_agent"):
    result = my_sync_agent.run(message)

When to use:

• Custom agent implementations that don't use veris.Runner or OpenAI's Runner
• Direct LLM API calls with tool execution loops
• Any code where decorated tools should be mocked during simulations

Note: The Veris Runner (below) handles this automatically—you only need explicit context managers for custom implementations.

Veris Runner

For OpenAI Agents, use the Veris Runner to intercept tool calls without modifying tool code.

Installation

uv add veris-ai --extra agents

Basic Usage

from veris_ai import Runner
from agents import Agent, function_tool

@function_tool
def calculator(x: int, y: int) -> int:
    """Add two numbers."""
    return x + y

agent = Agent(
    name="Assistant",
    model="gpt-4",
    tools=[calculator],
)

# Use Veris Runner instead of OpenAI's Runner
result = await Runner.run(agent, "What's 10 + 5?")

Selective Tool Interception

from veris_ai import Runner, VerisConfig

# Only intercept specific tools
config = VerisConfig(include_tools=["calculator", "search"])
result = await Runner.run(agent, "Calculate 2+2", veris_config=config)

# Or exclude specific tools
config = VerisConfig(exclude_tools=["get_weather"])
result = await Runner.run(agent, "Check weather", veris_config=config)

Per-Tool Configuration

from veris_ai import Runner, VerisConfig, ToolCallOptions, ResponseExpectation

config = VerisConfig(
    tool_options={
        "calculator": ToolCallOptions(
            response_expectation=ResponseExpectation.REQUIRED,
            cache_response=True,
        ),
        "search": ToolCallOptions(
            response_expectation=ResponseExpectation.NONE,
        ),
    }
)

result = await Runner.run(agent, "Calculate and search", veris_config=config)

Development

# Install with dev dependencies
uv add veris-ai --extra dev

# Lint and format
ruff check --fix .
ruff format .

# Run tests
pytest tests/ --cov=veris_ai

# Type check
mypy src/veris_ai

License

MIT License - see LICENSE for details.