Configuration reference

Agent-Gantry is configured through the AgentGantryConfig model in agent_gantry.schema.config and can be loaded directly from YAML via AgentGantry.from_config("config.yaml"). This guide summarizes the available knobs and shows ready-to-use snippets for common deployments.

Loading from YAML

from agent_gantry import AgentGantry

gantry = AgentGantry.from_config("config.yaml")
await gantry.sync()

# config.yaml
vector_store:
  type: memory
embedder:
  type: sentence_transformers  # Uses lightweight simple embedder stub by default
routing:
  weights:
    semantic: 0.6
    intent: 0.15
    conversation: 0.1
    health: 0.1
    cost: 0.05
execution:
  default_timeout_ms: 30000
telemetry:
  type: console

Module-based tool loading

When your tools live in multiple files, you can import and deduplicate their registries without sharing vector stores:

• Pass modules=[...] into AgentGantry(...) to defer loading until the first sync()
• Use AgentGantry.from_modules([...], attr="tools") to build and populate a new gantry in one call
• Call collect_tools_from_modules([...], module_attr="tools") to merge into an existing instance; pending unsynced tools are imported and duplicates are skipped with a warning

# tools/payments.py
from agent_gantry import AgentGantry

tools = AgentGantry()

@tools.register
def refund(order_id: str, amount: float) -> str:
    """Issue a refund."""
    return f"Refunded {amount} for {order_id}"

# bootstrap.py
import asyncio
from agent_gantry import AgentGantry

async def main() -> None:
    gantry = await AgentGantry.from_modules(["tools.payments"], attr="tools")
    await gantry.sync()
    print(await gantry.retrieve_tools("refund an order"))

asyncio.run(main())

Core components

Vector stores

LanceDB supports db_path, dimension, and separate tools / skills tables. Remote store configs accept url, api_key, and collection_name.

Embedders

EmbedderConfig supports model, dimension (for Matryoshka truncation), and task_type (search_document, search_query, clustering, classification for Nomic).

Reranker

RerankerConfig toggles second-stage reranking. The Cohere reranker is implemented; other types fall back to None.

reranker:
  enabled: true
  type: cohere
  model: rerank-english-v3.0

Routing

RoutingConfig controls the semantic router:

• weights: blend semantic, intent, conversation, health, and cost signals
• enable_intent_classification, use_llm_for_intent
• enable_mmr, mmr_lambda

Execution

ExecutionConfig configures retries, timeouts, and circuit breaker thresholds:

• default_timeout_ms
• max_retries
• circuit_breaker_threshold
• circuit_breaker_timeout_s
• sandbox_type (none, subprocess, docker) – sandboxing not yet wired in the default executor

Telemetry

TelemetryConfig chooses the observability backend:

• enabled: set false for NoopTelemetryAdapter
• type: console (default), opentelemetry, or prometheus (PrometheusTelemetryAdapter)
• service_name, otlp_endpoint, prometheus_port

datadog is accepted by the schema but currently falls back to console logging.

MCP / A2A

• mcp.servers: list of MCPServerConfig entries (name, command, args, env, namespace)
• mcp.serve_mcp: enable serving as an MCP server (mode: dynamic, static, hybrid)
• a2a.agents: list of A2AAgentConfig entries (name, url, namespace)
• a2a.serve_a2a: expose the FastAPI-based A2A server on a2a_port

Ready-made configuration snippets

Local-first: LanceDB + Nomic + Prometheus metrics

vector_store:
  type: lancedb
  db_path: .agent_gantry/lancedb
  dimension: 768
embedder:
  type: nomic
  model: nomic-ai/nomic-embed-text-v1.5
  dimension: 768
  task_type: search_document
telemetry:
  type: prometheus
  service_name: agent_gantry_local
  prometheus_port: 9090
reranker:
  enabled: false
execution:
  default_timeout_ms: 30000

Install extras:

pip install agent-gantry[lancedb,nomic]

Remote-ready: Qdrant + OpenAI embeddings + Cohere reranker

vector_store:
  type: qdrant
  url: https://qdrant.example.com
  api_key: ${QDRANT_API_KEY}
  collection_name: agent_gantry
embedder:
  type: openai
  api_key: ${OPENAI_API_KEY}
  model: text-embedding-3-small
reranker:
  enabled: true
  type: cohere
  model: rerank-english-v3.0
telemetry:
  type: opentelemetry
  service_name: agent_gantry_prod
  otlp_endpoint: https://otel.example.com
mcp:
  serve_mcp: true
  mcp_mode: dynamic

Install extras:

pip install agent-gantry[vector-stores,openai]
pip install cohere  # reranker model

Tuning sync behavior

• auto_sync: automatically embed and upsert pending tools on retrieval / execution
• sync_on_register: immediately embed and upsert each tool when registered

For large catalogs, disable auto_sync and call await gantry.sync() after batch registration.

Health checks

AgentGantry.health_check() reports the status of the vector store, embedder, and telemetry adapter. Remote adapters without endpoints will report unhealthy, which is expected for stubbed vector stores until real endpoints are configured.