Set up with AI

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.

#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 and integration matrix 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. 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.

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 and the selected runtime's lifecycle guidance. Account for completed and interrupted streams, failures and short-lived processes. Read the privacy controls 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 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 and troubleshooting.

#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 without claiming they were completed.