# Set up with AI | Tracehatch

> Let your coding agent inspect the codebase, choose a supported integration, and verify your application's traces.

Source: https://tracehatch.com/docs/ai-setup
Markdown: https://tracehatch.com/docs/ai-setup.md
Documentation index: https://tracehatch.com/llms.txt
SDK version documented: 0.15.1

Give your coding agent the prompt from **Project setup → Set up with AI**.
It includes this guide, your installation's API address and a link back to
project setup. When your agent needs the project key, save it in your private
server environment through the setup's API key step. The prompt contains no secret.

The instructions below are for the agent working in your codebase. Read the
linked pages as Markdown by appending `.md`, or use the [docs index](https://tracehatch.com/llms.txt).

## Inspect before choosing

Read the repository's instructions and inspect its language, package manager,
locked dependency versions, server runtime, deployment lifetime and actual
model-call sites. Check for existing Tracehatch or OpenTelemetry configuration.
In a monorepo, identify the server package that makes those calls.

Use the [framework and runtime guide](https://tracehatch.com/docs/sdk/frameworks.md) and
[integration matrix](https://tracehatch.com/docs/sdk/integrations.md) to choose the smallest supported
change. Direct provider clients, AI SDK, LangChain and other languages have
different recipes. A detected dependency alone does not establish support;
check the operations and versions actually used. Explain an unsupported path
instead of inventing an integration or upgrading the application's stack to
match an example.

## Implement the matching recipe

Follow the selected recipe and [configuration guide](https://tracehatch.com/docs/sdk/configuration.md).
Install in the correct server package using its existing package manager, and
update its lockfile. Use the documented package or source download: some
integrations require an archive and matching receiver, and are not yet
published to a package registry. Check that required exports exist before
using them; a matching version number alone is not proof.

Preserve existing provider credentials, models, requests, retry behavior and
application responses. Reuse existing telemetry configuration and instrument
each call once. Wrap the actual client or enable the documented framework hook;
an outer `observe()` alone does not capture hidden model calls. Add run, session
or tool boundaries only where the application supplies real identity or
execution evidence. See [tracing](https://tracehatch.com/docs/sdk/tracing.md).

Reuse `TRACEHATCH_API_KEY` from the private server environment without displaying
its value. If missing, ask the user to save the project setup key locally and
continue when it is available. Never ask them to paste it into agent chat, put
it in source or logs, or expose it through a public environment variable. Keep
environment files ignored and use placeholders in committed examples. A key
selects both project and environment; do not silently reuse one from another
project.

Use the API base supplied in the setup prompt, never the dashboard address.
Without a supplied address, this installation's API base is `https://api.tracehatch.com/api/v1`.
For native capture, pass it as `baseUrl` when it differs from the hosted
default. For OTLP, append `/otlp/v1/traces` to that API base and use the recipe's
HTTP exporter. Do not invent an SDK environment variable for the destination.

Follow [delivery and flushing](https://tracehatch.com/docs/sdk/delivery.md) and the selected
[runtime's lifecycle guidance](https://tracehatch.com/docs/sdk/frameworks.md). Account for completed and
interrupted streams, failures and short-lived processes. Read the
[privacy controls](https://tracehatch.com/docs/concepts/privacy.md) before changing body capture or
redaction; preserve the application's existing policy.

## Verify the application

Run the relevant checks already used by the repository. A
[connection check](https://tracehatch.com/docs/verify.md) can test credentials and delivery, but a
diagnostic or downloaded example does not prove the application's calls are
recorded.

Before the final application action, tell the user which runtime, framework and
provider you integrated. Ask them to return to the project setup link, choose
the key environment, open **Verify**, select that runtime/framework/provider,
and click **Verify this integration**. Choose what the action actually captures:
use **Model calls** if it does not execute tools or report usage. Wait until
the page finishes preparing verification and says to trigger the action.
Changing the integration or capture expectations starts a fresh verification
window; an earlier trace does not qualify. Then trigger one existing AI action,
or give the user exact steps to trigger it.
Do not repeat a billable model call just to retry telemetry delivery.

Confirm the processed application trace in the dashboard: the correct project
and environment, the action just performed, and its model steps with reported
usage where available. An ingest key cannot read traces. If you cannot access
that evidence, leave dashboard verification explicitly pending for the user;
tests passing or an accepted export is not proof of a processed application
trace. See [verification](https://tracehatch.com/docs/verify.md) and
[troubleshooting](https://tracehatch.com/docs/reference/troubleshooting.md).

## Hand back a clear result

Report the selected integration, files changed, checks run, and what is still
needed. Distinguish code configured, connection checked and application trace
verified. Include the project setup link and the next action when verification
is pending. Local setup does not configure production; describe any remaining
[deployment steps](https://tracehatch.com/docs/deploy.md) without claiming they were completed.