# Agentegrity

> Connect the agent in this project to an Agentegrity Pro workspace so every run streams signed evidence to the console. Use when the user asks to connect, wire, instrument, onboard or set up Agentegrity, or to get sessions, integrity scores, drift or attestation certificates for an agent.

- Skill: `cogensec/agentegrity` (Agent Skill)
- Install (CLI): `npx skillmds@latest add cogensec/agentegrity`
- Raw SKILL.md: https://api.skillmd.com/api/skills/cogensec/agentegrity/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: Cogensec (https://skillmd.com/u/cogensec)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/cogensec/agentegrity

---


# Connect this project to Agentegrity

Agentegrity Pro is a self-hosted integrity platform for autonomous agents.
An agent instrumented with the open-source `agentegrity` SDK evaluates every
tool call locally, and an HTTP exporter streams each session to the user's
console, where it becomes live sessions, per-agent posture, drift findings and
Ed25519-signed attestation certificates.

This skill takes the project you are in from "has an agent" to "its runs show
up in the user's console". Zero code changes are the goal: the SDK attaches
its exporter from two environment variables.

## What you need from the user

Two values, handled differently. The workspace URL is not a secret and the
user can tell you in chat. The ingest token is a live bearer credential and
must never pass through the conversation: a coding agent's transcript
persists. Ask for the URL, and ask the user to put the token in place
themselves. One message, up front, saying where each comes from:

| Value | Env var | How it reaches the agent |
|---|---|---|
| Workspace URL | `AGENTEGRITY_EXPORTER_URL` | The user tells you. It is the console's origin, e.g. `https://console.acme.ai`, shown on the **Connect agent** card (topbar) and under **Settings → Ingest Tokens**. |
| Ingest token | `AGENTEGRITY_TOKEN` | The user sets it; you never see it. `agk_live_…`, minted on the same card or under **Settings → Ingest Tokens** by a workspace admin, shown once. They add `AGENTEGRITY_TOKEN=…` to the project's git-ignored `.env` (or export it in the shell they will run the agent from), then tell you it is in place. |

Rules for the token:

- Never ask the user to paste it into the conversation. If they do anyway,
  tell them to revoke it under **Settings → Ingest Tokens** and mint a new
  one, because the transcript keeps it.
- Never write it into source code, a Dockerfile, a notebook cell, a commit,
  a log line or a chat message. It lives in a git-ignored `.env` or the
  user's secret store, put there by the user.
- Never echo it back or print `$AGENTEGRITY_TOKEN`. Confirm presence only,
  e.g. `test -n "$AGENTEGRITY_TOKEN" && echo set` or
  `grep -q '^AGENTEGRITY_TOKEN=.' .env && echo set`.
- If the user has no admin role, tell them an admin must mint it. Do not try
  to create one another way.

## Steps

### 1. Identify the agent framework

Look at the project's dependencies and imports, then pick the matching SDK
extra. If more than one matches, ask.

| Framework in the project | Install | Mode |
|---|---|---|
| Claude Agent SDK (`claude_agent_sdk`) | `pip install "agentegrity[claude]>=0.10"` / `npm i @agentegrity/claude-sdk` | enforce |
| OpenAI Agents SDK (`agents`) | `pip install "agentegrity[openai-agents]>=0.10"` / `npm i @agentegrity/openai-agents` | enforce |
| AWS Bedrock Agents / Strands | `pip install "agentegrity[bedrock-agents]>=0.10"` | enforce |
| Agno | `pip install "agentegrity[agno]>=0.10"` | enforce |
| LangChain / LangGraph | `pip install "agentegrity[langchain]>=0.10"` / `npm i @agentegrity/langchain` | observe |
| CrewAI | `pip install "agentegrity[crewai]>=0.10"` / `npm i @agentegrity/crewai` | observe |
| Google ADK | `pip install "agentegrity[google-adk]>=0.10"` / `npm i @agentegrity/google-adk` | observe |
| Microsoft AutoGen | `pip install "agentegrity[autogen]>=0.10"` | observe |
| Vercel AI SDK | `npm i @agentegrity/vercel-ai` | observe |

"Enforce" adapters can veto a blocked tool call before it runs; "observe"
adapters record the decision but cannot prevent execution. Tell the user
which one they are getting.

Any agent that already emits OpenTelemetry GenAI spans can also send them to
`POST /v1/traces` on the workspace URL with
`OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer <token>"`, but OTLP alone
cannot produce an attestation certificate. Prefer a native adapter; offer
OTLP only when no adapter fits.

### 2. Install the SDK

Use the project's own package manager and lockfile (uv, poetry, pip, pnpm,
npm…). Pin `>=0.10.0`: that is the release with the `agentegrity` command,
the built-in `HTTPExporter` and env auto-attach.

### 3. Instrument the agent

Add the adapter at the point where the agent is constructed. One or two
lines, following the pattern for the framework:

```python
# Claude Agent SDK
from agentegrity.claude import hooks, report
ClaudeSDKClient(options=ClaudeAgentOptions(hooks=hooks()))

# OpenAI Agents SDK
from agentegrity.openai_agents import run_hooks
await Runner.run(agent, input=..., hooks=run_hooks())

# LangChain / LangGraph
from agentegrity.langchain import instrument_graph
graph = instrument_graph(my_graph)

# CrewAI · AutoGen
from agentegrity.crewai import instrument   # or agentegrity.autogen
instrument()

# Google ADK · Agno · Bedrock (Strands)
from agentegrity.google_adk import instrument      # instrument(agent)
from agentegrity.agno import instrument            # agent = instrument(agent, enforce=True)
from agentegrity.bedrock import instrument_strands # agent = instrument_strands(agent, enforce=True)
```

```ts
// Vercel AI SDK
import { instrument } from "@agentegrity/vercel-ai";
await streamText({ model, prompt, experimental_telemetry: instrument() });
```

Do not write an exporter class. With the two env vars set, the SDK attaches
its `HTTPExporter` on adapter construction. Only if the project pins an SDK
older than 0.10.0 should you register one by hand; the pattern is in the
platform's wiring guide (`docs/WIRING.md` in `agentegrity-pro`).

### 4. Set the two environment variables

Write the URL where the project already keeps configuration, and leave a
placeholder for the token that the user fills in themselves:

```
AGENTEGRITY_EXPORTER_URL=https://console.acme.ai
AGENTEGRITY_TOKEN=   # the user pastes the agk_live_… token here, never you
```

Check that file is git-ignored before adding the placeholder. Then ask the
user to fill the token in (or export it in their shell) and confirm it is
present without printing it. Do not go on to step 5 until they have.

Optional: `AGENTEGRITY_FLUSH=on_end` buffers events and sends them when the
session closes instead of per event.

### 5. Verify before declaring success

Run, with the env loaded:

```bash
agentegrity pro --push
```

It calls `GET /ingest/verify` with the token and prints
`✓ connected to <url> (workspace: <name>)`, then emits one labelled test
session so a row lands in the console's **Sessions** page. Then run the
agent for real, wrapped so the child process inherits the env:

```bash
agentegrity pro -- python my_agent.py
```

A `401` means the token was rejected: the user mints a new one under
**Settings → Ingest Tokens**. A `402` means the workspace's trial has
lapsed. Anything else that fails is network: the exporter is fail-open, so
the agent keeps running and nothing arrives.

### 6. Hand back

Tell the user, in this order:

1. Which framework and mode (enforce / observe) you wired.
2. The file(s) you touched and the two variables you set (name only, never
   the token's value).
3. That they should open the console: the session from `agentegrity pro
   --push` is under **Sessions**, and the agent appears under **Agents**
   after its first real run.

## Reference

- Wire contract: `POST /sessions`, `POST /sessions/{id}/events`,
  `POST /sessions/{id}/end`, all `Authorization: Bearer <token>`; session
  ids are 32-char lowercase hex. The SDK's exporter already conforms.
- Platform: https://github.com/Cogensec/agentegrity-pro (`docs/WIRING.md`,
  `docs/openapi.yaml`). SDK: https://github.com/Cogensec/agentegrity.