Voyage AI Integration with Future AGI for Embedding and Rerank Tracing

traceAI-voyage traces the official Voyage AI Python client, voyageai.Client and voyageai.AsyncClient. traceAI-openai does not trace Voyage: it wraps the OpenAI client only and never sees voyageai.Client. Use this package for Voyage embeddings and reranking.

1. Installation

Use Python 3.10 through 3.13.

pip install "traceAI-voyage>=0.1.2" "fi-instrumentation-otel>=1.2.3"

The supported Voyage client range is voyageai>=0.3.7,<1. Install fi-instrumentation-otel>=1.2.3 as shown above so content-hide settings also suppress error details.

2. Set environment variables

import os

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

3. Register and instrument

import voyageai
from fi_instrumentation import register
from fi_instrumentation.fi_types import ProjectType
from traceai_voyage import VoyageInstrumentor

trace_provider = register(project_type=ProjectType.OBSERVE, project_name="my-rag-app")
VoyageInstrumentor().instrument(tracer_provider=trace_provider)

client = voyageai.Client()  # reads VOYAGE_API_KEY
client.embed(["What is the capital of France?"], model="voyage-3.5", input_type="query")
client.rerank("capital of France", ["Paris is...", "Berlin is..."], model="rerank-2.5", top_k=1)

trace_provider.force_flush()

The methods are patched on the client classes, so a client created before instrument() is traced too. uninstrument() restores the originals.

4. View the trace

Open Observe in Future AGI and select the my-rag-app project. Each call appears as a voyage.embed or voyage.rerank span.

What is captured

These methods are traced on both voyageai.Client and voyageai.AsyncClient:

Method	Span name	Span kind
embed	voyage.embed	EMBEDDING
multimodal_embed	voyage.multimodal_embed	EMBEDDING
contextualized_embed	voyage.contextualized_embed	EMBEDDING
rerank	voyage.rerank	RERANKER

One span per call, including a whole batch and the client’s own retries. Spans nest under the active span, so an agent or chain span becomes their parent. Recorded: provider voyage, model, server.address (host only), input/document/result counts, input_type, output dimension, top_k, and the token total reported by the client (shown as input tokens; never estimated, no cost set). Multimodal text tokens and image/video pixels are recorded separately; pixels are not added to the token total.

By default, a failed call is an ERROR span with the error type and message (API key removed). For multimodal_embed and contextualized_embed, only the error type and a generic message are recorded, because SDK errors can echo media or whole documents. The privacy settings below can suppress error messages while preserving the error type and ERROR status. No stack trace is exported.

The deprecated module functions voyageai.get_embedding(s) and the TypeScript client are not traced. Embedding vectors are never recorded.

Privacy

This package follows the standard traceAI TraceConfig. Set privacy environment variables before calling register() and instrument().

Setting	Recorded
Default	Rerank query and relevance scores. Embedding inputs and rerank documents are not recorded.
VoyageInstrumentor().instrument(..., capture_content=True)	Also embedding text inputs and rerank documents (first 64 items, each cut to 2 KB). Media in multimodal inputs is recorded as [media omitted].
FI_HIDE_INPUTS=true and FI_HIDE_OUTPUTS=true	Hides query, texts, documents, scores and error messages; counts, model, tokens and error types remain.
FI_PII_REDACTION=true	Applies pattern-based PII redaction to recorded strings.

Error-message suppression requires fi-instrumentation-otel>=1.2.3, installed above. Leave FI_HIDE_ERROR_DETAILS unset or set it to true; do not override it with FI_HIDE_ERROR_DETAILS=false or TraceConfig(hide_error_details=False). Those overrides can expose response content in exception messages and ERROR status descriptions even when inputs and outputs are hidden.

Media payloads, media URLs and embedding vectors are never recorded. PII redaction can also match long numeric relevance scores; set FI_HIDE_OUTPUTS=true if you do not need scores in traces.

Hosts and base_url

The instrumentor never sets base_url. The Voyage client chooses the host from the key (keys created in MongoDB Atlas go to ai.mongodb.com, Voyage platform keys to api.voyageai.com); a base_url you pass to the client wins. A key sent to the wrong host fails in the client, the span records that error, and nothing retries elsewhere.

Troubleshooting

• No Voyage spans after installing traceAI-openai. That package cannot see voyageai.Client. Install traceAI-voyage.
• Token counts look doubled. Another instrumentation that wraps the same Voyage call also records usage; disable one.
• Texts missing on embedding spans. They are off by default; pass capture_content=True.
• No multimodal_embed or contextualized_embed spans. Upgrade traceAI-voyage to the version in the install step.
• Atlas key fails on api.voyageai.com. Pass the host you need as base_url when building the client.