Trace LangChain Deep Agents with Future AGI

Trace Deep Agents model calls, built-in tools and task subagents in Future AGI using the maintained traceAI LangChain integration. create_deep_agent builds a LangGraph graph, so you do not need a separate Deep Agents instrumentor.

Prerequisites

• Python 3.11–3.13, a Future AGI account and API keys.
• An OpenAI API key for the model used below, or a supported chat model with its own provider credentials.
• Deep Agents 0.7.28 requires langchain-core>=1.6.11; your model adapter may require a newer core. Let pip resolve compatible LangChain dependencies rather than pinning an older core version.

1. Install

pip install "traceAI-langchain==0.2.1" "fi-instrumentation-otel==1.2.3" "deepagents==0.7.28" "langchain-openai==1.7.4"

traceAI-langchain 0.2.1 maps configurable.thread_id to session.id. The core package supplies the privacy controls used below.

2. Configure credentials and privacy

Set these variables before starting Python. Filesystem tools can include file contents in their arguments and results; this setup hides input, output and error details from traces.

export FI_API_KEY="YOUR_API_KEY"
export FI_SECRET_KEY="YOUR_SECRET_KEY"
export OPENAI_API_KEY="YOUR_MODEL_PROVIDER_KEY"
export FI_HIDE_INPUTS=true
export FI_HIDE_OUTPUTS=true
export FI_HIDE_ERROR_DETAILS=true

3. Instrument and run the agent

Call register(), then instrument(), then build the agent. Save this example as deep_agent.py. The weather tool returns sample data, and StateBackend keeps files in graph state rather than writing them to disk.

from deepagents import create_deep_agent
from deepagents.backends import StateBackend
from fi_instrumentation import register
from fi_instrumentation.fi_types import ProjectType
from langchain_core.tools import tool
from langchain_openai import ChatOpenAI
from traceai_langchain import LangChainInstrumentor

trace_provider = register(
    project_type=ProjectType.OBSERVE,
    project_name="deep-agents-app",
)
LangChainInstrumentor().instrument(tracer_provider=trace_provider)


@tool
def lookup_weather(city: str) -> str:
    """Return sample weather for a city."""
    return f"Sample forecast: sunny in {city}"


agent = create_deep_agent(
    model=ChatOpenAI(model="gpt-5.5"),
    tools=[lookup_weather],
    system_prompt="You are a travel assistant.",
    backend=StateBackend(),
)

try:
    result = agent.invoke(
        {"messages": [{"role": "user", "content": "Save my Paris trip notes in /trip.txt, check Paris weather, then ask a general-purpose subagent to list the files."}]},
        config={"configurable": {"thread_id": "trip-42"}},
    )
    print(result["messages"][-1].content)
finally:
    trace_provider.force_flush()

python deep_agent.py

Always pass a model explicitly instead of relying on Deep Agents’ deprecated default. thread_id groups spans into a tracing session; it does not persist agent state between invocations without a checkpointer.

4. View the trace

Open Observe, select deep-agents-app and open the latest trace. Look for the model calls, the tools the agent chose to run and session trip-42. If the agent delegates through task, expand that tool span to inspect the nested subagent calls.

What you see	Source
LLM spans with model name and token usage	The chat model’s usage_metadata, when supplied by the provider. Token counts belong to model spans, not every graph node.
TOOL spans	Built-in filesystem tools such as write_file and ls, the task delegation tool and your application tools. Shell execution requires a sandbox backend.
Subagent spans	Calls made by a task subagent, such as general-purpose, nested under the task that invoked it.
CHAIN or AGENT spans	Graph nodes and middleware; node names containing “agent” are classified as AGENT.
Session	configurable.thread_id becomes session.id unless an explicit session context or metadata["session_id"] takes precedence.
Errors	Failed calls have ERROR status. A handled tool error does not necessarily fail the root agent run.

Privacy

Without privacy flags, the integration captures prompts, responses, tool arguments and tool results, which can include file contents. The input and output flags above redact or omit those content fields. Keep session IDs, tool names and custom metadata free of sensitive data; these flags are not a general-purpose metadata scrubber.

Error details are a separate setting. With FI_HIDE_ERROR_DETAILS=false, a failed span’s status description contains the exception message without the formatted traceback, but its exception event can contain both the message and a stack trace, including local file paths. With FI_HIDE_ERROR_DETAILS=true, the core removes error messages, stack traces and the status description while preserving ERROR status and exception types.

If FI_HIDE_ERROR_DETAILS is unset, the core derives it from the content-hiding flags, including FI_HIDE_INPUTS and FI_HIDE_OUTPUTS. An explicit false overrides that derivation, so set it to true when error details must stay private.

To configure privacy in code instead, replace the earlier instrument() call with this block before creating the agent:

from fi_instrumentation import TraceConfig

LangChainInstrumentor().instrument(
    tracer_provider=trace_provider,
    config=TraceConfig(
        hide_inputs=True,
        hide_outputs=True,
        hide_error_details=True,
    ),
)

Troubleshooting

• No session grouping: use traceAI-langchain 0.2.1 and pass a non-empty configurable.thread_id. Check that an explicit session context or metadata["session_id"] is not overriding it.
• No spans after exit: keep trace_provider.force_flush() in a finally block so it runs after failed calls too.
• Unexpected model calls: middleware can add grading or summarization calls. Inspect the parent node before treating them as duplicates, and instrument LangChain only once per process.
• No content in spans: this guide hides inputs and outputs. To capture them, change the corresponding privacy flags only when your data policy allows it; keep error-detail hiding enabled independently.

This guide covers the Python create_deep_agent application API, not Deep Agents JavaScript, CLI or ACP sessions. For other LangGraph applications, use the LangGraph guide.