Trace TavilyClient and AsyncTavilyClient search and extraction calls in
Future AGI.
Requires Python 3.10–3.13, tavily-python>=0.8.4,<1, and
fi-instrumentation-otel>=1.1.0.
pip install "traceAI-tavily>=0.1.0"Set FI_API_KEY, FI_SECRET_KEY and TAVILY_API_KEY in your environment.
For a self-hosted Future AGI deployment, also set FI_BASE_URL to its base URL.
import os
from fi_instrumentation import register
from fi_instrumentation.fi_types import ProjectType
from tavily import TavilyClient
from traceai_tavily import TavilyInstrumentor
tracer_provider = register(
project_name="tavily-example", project_type=ProjectType.OBSERVE, verbose=False
)
TavilyInstrumentor().instrument(tracer_provider=tracer_provider)
client = TavilyClient(api_key=os.environ["TAVILY_API_KEY"])
response = client.search("What is OpenTelemetry?", max_results=2)
print("results:", len(response["results"]))
tracer_provider.force_flush()Open the tavily-example project in Future AGI to find the tavily.search
span. Calls made inside an active OpenTelemetry span appear as its children.
The instrumentor also supports using_session, using_user and
suppress_tracing from fi_instrumentation.
Both client classes support these spans. With AsyncTavilyClient, await the
method and close the client with await client.close() when finished.
The deprecated tavily.Client subclass inherits the synchronous instrumentation.
| Method | Span | Kind |
|---|---|---|
search |
tavily.search |
RETRIEVER |
extract |
tavily.extract |
TOOL |
Private HTTP helpers and convenience methods have no separate spans. If a convenience method calls a supported method, that underlying call is traced once. Usage, credits and search options are not recorded.
- Search queries and extract reranking queries are recorded as
input.value, with client keys redacted and text capped at 1,024 UTF-8 bytes. Search also recordsgen_ai.retrieval.query. - Result bodies and URL arguments are not recorded. Extraction records URL counts instead. Text you put into a query is still input text; hide inputs if it is sensitive.
tavily.result_countrecords the number of results when present;tavily.failed_result_countrecords failed extractions. Unknown counts are omitted.- Set
FI_HIDE_INPUTS=trueto mask inputs, omit retrieval queries and remove search/extract query text from error details. - Set
FI_PII_REDACTION=trueto redact supported personal-data patterns before query text is capped, so truncation cannot leave a recognizable PII fragment. You can also passconfig=TraceConfig(hide_inputs=True, pii_redaction=True)toinstrument(), importingTraceConfigfromfi_instrumentation.
Errors are re-raised unchanged. Search HTTP/transport failures record only the
exception type, never messages or tracebacks: these errors can include custom
endpoint credentials. Other search errors retain scrubbed, frames-free summaries.
Extraction failures also record only the type, because errors can echo sensitive
URL arguments. Type-only recording applies even with default privacy settings
and on the minimum supported core version. Cancelling an async call sets ERROR
and tavily.cancelled=true, without an exception event. Instrumentation failures do not replace your SDK
result or exception.
For langchain_tavily.TavilySearch or the community Tavily tool, use
traceAI-langchain to trace the tool call. This package targets
bare Tavily clients, not those tool wrappers.
If your own LangChain tool calls TavilyClient, enabling both instrumentors
creates a tool span and a lower-level client span. Enable only LangChain tracing
if you want one span per tool call. To hide tool results that become a later
agent input, set both FI_HIDE_INPUTS=true and FI_HIDE_OUTPUTS=true.
- No spans: instrument before calling the client, pass the provider returned
by
register(), and flush before a short-lived process exits. Check thetraceai_tavilylogger for an unsupported SDK version or a moved method. - Stop tracing:
TavilyInstrumentor().uninstrument()restores the original client methods; subsequent calls are not traced.