Skip to content

Use fastaiagent with your existing framework

Your agent is built in LangGraph, CrewAI or Pydantic AI, and you are not going to rewrite it as a fa.Agent. You can still use tracing, the Local UI, guardrails, evals, knowledge bases, prompts and the control plane with it. This page shows how. Every snippet runs as written against the framework's own public API. None of it imports framework code from fastaiagent.

Removed in 1.96.0

The fastaiagent.integrations.langchain, .crewai and .pydanticai adapters and the [langchain], [crewai] and [pydanticai] extras are gone. They wrapped each framework's internals, so they broke whenever a framework changed. The OpenTelemetry route below needs no adapter. The last section maps each removed function to its replacement.

You want How
Traces in the Local UI An OpenInference instrumentor + fa.enable_otel_capture()
A named run (agent name, prompt link, plane linkage) A root span from fa.trace_context(...)
Guardrails guardrail.execute(...) around the call
Evals, each case linked to its trace fa.evaluate(...) on a plain function
Knowledge-base search kb.search(...) inside one of the framework's own tools
Registry prompts PromptRegistry().get(...).format(...) as the system prompt
Plane tool approvals fa.check_tool_call(...) inside the framework's tool

1. Trace the run

Install the framework's OpenInference instrumentor, instrument, and call fa.enable_otel_capture(). The spans land in .fastaiagent/local.db and render in fastaiagent ui with model, tokens, cost, input and output. Capture any OTel / OpenInference framework explains what the capture does.

pip install fastaiagent langgraph langchain-openai openinference-instrumentation-langchain
import fastaiagent as fa
from openinference.instrumentation.langchain import LangChainInstrumentor

fa.enable_otel_capture()
LangChainInstrumentor().instrument()

from langchain.agents import create_agent
from langchain_openai import ChatOpenAI

agent = create_agent(ChatOpenAI(model="gpt-4o-mini"), tools=[], system_prompt="Be brief.")
agent.invoke({"messages": [("user", "Where is order A100?")]})
pip install fastaiagent crewai openinference-instrumentation-crewai openinference-instrumentation-openai
import fastaiagent as fa
from openinference.instrumentation.crewai import CrewAIInstrumentor
from openinference.instrumentation.openai import OpenAIInstrumentor

fa.enable_otel_capture()
CrewAIInstrumentor().instrument()
OpenAIInstrumentor().instrument()   # the model calls: tokens and cost

from crewai import LLM, Agent, Crew, Task

agent = Agent(role="Support", goal="Answer briefly", backstory="You help customers.",
              llm=LLM(model="gpt-4o-mini"))
task = Task(description="Where is order A100?", expected_output="A short answer", agent=agent)
Crew(agents=[agent], tasks=[task]).kickoff()
pip install fastaiagent pydantic-ai openinference-instrumentation-pydantic-ai

Pydantic AI writes its own spans. Add OpenInference's span processor to a provider you own before fa.enable_otel_capture(), so the spans carry the input, output and span kinds the UI reads:

from openinference.instrumentation.pydantic_ai import OpenInferenceSpanProcessor
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider

import fastaiagent as fa

provider = TracerProvider()
provider.add_span_processor(OpenInferenceSpanProcessor())
trace.set_tracer_provider(provider)
fa.enable_otel_capture()   # joins your provider

from pydantic_ai import Agent

Agent.instrument_all(True)
agent = Agent("openai:gpt-4o-mini", system_prompt="Be brief.")
agent.run_sync("Where is order A100?")

Without the processor, the run is still captured, but its spans have no input, output or span kind in the UI.

2. Name the run

The framework's root span says nothing about which agent ran (LangGraph, Crew_<uuid>.kickoff, agent run). Open your own root span with fa.trace_context(...) and put the run under it. agent.name gives the run its name in the UI and is what the plane matches to an agent. Step 6 adds the prompt the run used.

import fastaiagent as fa

with fa.trace_context(
    "agent.support",
    **{"agent.name": "support", "input.value": question},
) as span:
    answer = run_my_agent(question)          # your framework call
    span.set_attribute("output.value", answer)

The SDK does not invent a name. An unnamed run still traces, but it is not linked to an agent.

3. Guardrails

Run the check yourself around the framework call. execute returns a verdict and never raises for a failed check; you decide what a block means. Inside the root span from step 2, it also writes a row to the Guardrail events page, linked to the run's trace.

import fastaiagent as fa

no_pii = fa.no_pii(position="input")


def guarded(question: str) -> str:
    with fa.trace_context("agent.support", **{"agent.name": "support", "input.value": question}):
        verdict = no_pii.execute(question)
        if verdict.action_taken == "blocked":
            return f"Blocked: {verdict.message}"
        if verdict.action_taken == "masked":
            question = verdict.modified_data
        return run_my_agent(question)

action_taken is none for a pass, otherwise blocked, warned or masked (with the safe text in modified_data), following the rule's action. In async code, await no_pii.aexecute(question).

Guardrails authored on the plane come from fa.plane_guardrails_for_agent("support"). The plane scopes a rule to an agent by its id, so push the agent first (step 7): the SDK then resolves the name to its id. For a name this process has not pushed, only the domain-wide rules come back, and the SDK logs a warning. For the plane to record a verdict, emit it as a GUARDRAIL span with fa.emit_guardrail(...). Guardrails & evals without the runtime covers both, and the on_error policy.

4. Evals

fa.evaluate takes any function from input to output:

import fastaiagent as fa

results = fa.evaluate(
    agent_fn=run_my_agent,
    dataset=[
        {"input": "Where is order A100?", "expected_output": "shipped"},
        {"input": "Where is order B200?", "expected_output": "processing"},
    ],
    scorers=["contains"],
    run_name="support-nightly",
    agent_name="support",
)
print(results.summary())

fa.evaluate runs four cases at once (concurrency=4), each sync call on its own thread. Two frameworks need a different function for that:

  • CrewAI: one Agent cannot run twice at the same time ("Executor is already running"). Build the agent and the crew inside the function.
  • Pydantic AI: pass an async function, so every case runs on one event loop. run_sync from several threads can hang once the model client has been used on another loop.
async def run_my_agent(question: str) -> str:   # Pydantic AI
    return (await agent.run(question)).output

Since 1.96.0, each case links to the trace its call started, so the Evals page opens the run behind a score. A function that returns an object with a trace_id sets the link itself. The same function works in Agent CI gates.

A plain fa.evaluate run stays local. When connected, the plane receives only runs that went through a gate (gate then record_gate_result, or the pytest gate). See Connected eval export.

5. Knowledge bases

Search a LocalKB inside one of the framework's own tools:

import fastaiagent as fa

kb = fa.LocalKB(name="policy", search_type="keyword")
kb.add("Customers may return items within 45 days of delivery.")


def search_policy(query: str) -> str:
    """Search the company policy knowledge base."""
    return "\n".join(hit.chunk.content for hit in kb.search(query, top_k=3))

Wrap search_policy with the framework's tool decorator (@tool from langchain_core.tools, @tool("search_policy") from crewai.tools, or Tool(search_policy) in Pydantic AI). With a root span from step 2, the retrieval span lands in the same trace as the run.

6. Prompts

Use a registry prompt as the system prompt, and stamp it on the root span with prompt.trace_attributes() so the run shows on the prompt's page:

import fastaiagent as fa

prompt = fa.PromptRegistry().get("support-system")
system_prompt = prompt.format(company="Northwind")

with fa.trace_context(
    "agent.support",
    **{"agent.name": "support"},
    **prompt.trace_attributes(),
):
    ...  # build the framework agent with system_prompt and run it

trace_attributes() gives the keys a native fa.Agent stamps: fastaiagent.prompt.name and .version, which the Local UI reads, and for a control-plane prompt .slug and .environment as well. The plane links a run to a prompt by slug and version, so a run stamped with only the name is on no prompt's page there.

7. The control plane

fa.connect(...) exports these traces like any other. Two things link them to an agent on the plane:

  1. The root span from step 2, carrying agent.name.
  2. An agent with that name on the plane. Push one that describes the agent:
import fastaiagent as fa

fa.connect(api_key="fa_k_…", target="https://<label>-dev.api.fastaiagent.net")
fa.Agent(
    name="support",
    system_prompt="You are a support agent.",
    llm=fa.LLMClient(provider="openai", model="gpt-4o-mini"),
).push()

The key needs the agent:write scope. See Registration. Push before step 3 asks for the agent's guardrails, so its name resolves to its plane id.

Tools the plane holds an approval policy for are not gated for you, because fa.Agent is not running them. Ask inside the tool with fa.check_tool_call:

def refund(order_id: str, amount: float) -> str:
    """Refund an order."""
    decision = fa.check_tool_call(
        "refund", {"order_id": order_id, "amount": amount}, agent="support"
    )
    if decision.decision != "allow":
        return f"Not done: {decision.reason or decision.decision}"
    return do_refund(order_id, amount)

It never pauses the run. On require_approval the plane records a pending request and your application collects the decision. Managed governance lists what it answers when the plane is unreachable.

Pydantic AI on a provider you own

Spans recorded on your own TracerProvider (the Pydantic AI setup in step 1) are sent to the plane only when a fastaiagent span ends. Put the run inside the fa.trace_context(...) root span from step 2 and they go out with it.

What is different from a native agent

  • Replay rebuilds only a fa.Agent run. A framework run can be viewed and compared, not forked and rerun.
  • CrewAI root spans are named Crew_<uuid>.kickoff and have no input, and the instrumentor writes some LLM spans with zero tokens. The root span from step 2 gives the run a name and an input.
  • Middleware, @idempotent, checkpoints and interrupt() belong to the fastaiagent runtime. Use the framework's own equivalents.

Moving from the removed integrations

Removed Use instead
langchain.enable(), crewai.enable(), pydanticai.enable() The instrumentor + fa.enable_otel_capture() (step 1)
with_guardrails(agent, ...) guardrail.execute(...) around the call (step 3)
as_evaluable(agent) A plain function passed to fa.evaluate (step 4)
kb_as_retriever(kb), kb_as_tool(kb) kb.search inside a framework tool (step 5)
prompt_from_registry(name) PromptRegistry().get(name).format(...) (step 6)
register_agent(agent, name=...) fa.Agent(name=...).push() while connected (step 7)
fastaiagent.integrations.agent_name(name) fa.trace_context("agent.<name>", **{"agent.name": name}) (step 2)
pip install "fastaiagent[langchain]" (and [crewai], [pydanticai]) pip install fastaiagent plus the framework and its instrumentor

The OpenAI and Anthropic SDK auto-tracing in fastaiagent.integrations is unchanged.