# AgentLeak — complete agent and developer guide

## What AgentLeak solves

An agent's final answer can be clean while sensitive data leaks through tool arguments, tool responses, shared memory, inter-agent messages, logs, or generated files. AgentLeak analyzes the full trace, detects sensitive material, reconstructs leak paths, calculates a deterministic Risk Index, and returns remediation evidence.

## Hosted service

- Base URL: https://www.agentleak.org
- Health: `GET /api/health`
- Capabilities and current limits: `GET /api/meta`
- Integrated API reference: `GET /docs/api`
- OpenAPI: `GET /openapi.json`
- JSON Schema catalog: `GET /api/schemas`
- Swagger fallback: `GET /api/docs`
- Authentication after onboarding: `X-AgentLeak-Key: ak_...`

## Autonomous quickstart

```bash
BASE=https://www.agentleak.org

curl -sS -X POST "$BASE/api/agent/onboard" \
  -H 'content-type: application/json' \
  -d '{"email":"owner@example.com","agent_name":"SupportBot"}'

export AGENTLEAK_KEY='ak_replace_with_returned_key'

curl -sS -X POST "$BASE/api/agent/register" \
  -H "X-AgentLeak-Key: $AGENTLEAK_KEY" \
  -H 'content-type: application/json' \
  -d '{"agent_card":{"name":"SupportBot","description":"Handles support tickets","capabilities":["ticket_triage","crm_lookup"],"privacy":{"declared_data_types":["email","account_id"]}}}'

curl -sS -X POST "$BASE/api/selftest" \
  -H "X-AgentLeak-Key: $AGENTLEAK_KEY" \
  -H 'content-type: application/json' \
  -d '{"trace":{"agent_name":"SupportBot","events":[{"channel":"tool_call","source":"agent","target":"crm","content":{"email":"canary@example.test"}},{"channel":"final_output","source":"agent","target":"user","content":"Ticket updated"}]}}'

curl -sS "$BASE/api/agent/status" -H "X-AgentLeak-Key: $AGENTLEAK_KEY"
```

## Agent loop

`onboard -> register -> code scan + self-test -> improve -> status -> fix -> repeat`

- `POST /api/agent/onboard`: create an account, project, and project-scoped key.
- `POST /api/agent/register`: declare the agent card and optional source location.
- `POST /api/agent/code`: scan inline files, a zip, or an explicitly declared GitHub repository.
- `POST /api/selftest`: analyze one runtime trace.
- `POST /api/agent/improve`: analyze, compare with the previous run, and return prioritized `next_steps`.
- `GET /api/agent/status`: read the latest run, progression, compliance posture, code scan, and remaining work.

## Developer quickstart

```bash
pip install agentleak
agentleak init
agentleak run --scenario healthcare_patient_summary
agentleak run --trace traces/latest.json --fail-under 70
agentleak schema
agentleak scan . --format sarif --output reports/agentleak.sarif
```

## Declarative privacy assertions

Configure `privacy_policy` with `max_risk_index`, `max_findings`, forbidden
levels, channels or data types, and optionally `require_explicit_vault`. Every
configured assertion must pass. Violations block the run and include affected
finding IDs in the report. Fetch the exact contract from
`GET https://www.agentleak.org/api/schemas/privacy-policy`.

## Machine contracts

`GET https://www.agentleak.org/api/schemas` lists versioned Draft 2020-12 schemas for config,
traces, events, findings, reports, privacy policies, red-team requests, code
scans and agent cards. The local equivalent is `agentleak schema [name]`.

```python
from agentleak import AgentLeakRunner, Trace

trace = Trace(run_id="demo", agent_name="support-bot")
trace.add_event(channel="tool_call", source="agent", target="crm", content={"email": "canary@example.test"})
trace.add_event(channel="final_output", source="agent", target="user", content="Done")
result = AgentLeakRunner().analyze(trace)
print(result.risk_index, result.verdict)
```

Framework adapters cover LangChain/LangGraph, CrewAI, AutoGen, OpenAI Agents/Swarm, LlamaIndex, Semantic Kernel, Pydantic AI, smolagents, Google ADK, computer-use agents, OpenTelemetry/OpenInference, MCP, and generic event recorders.

## Interpretation

- Risk Index ranges from 0 to 1; higher means a larger weighted share of sensitive inventory leaked.
- Privacy score ranges from 100 to 0 and is the inverse presentation of risk.
- L4 is critical, L3 high, L2 medium, and L1 low.
- A passing trace is evidence for that trace and configured policy, not a universal guarantee or legal certification.

## Safe operating rules

1. You MUST have authorization from the system owner before submitting its source code or traces.
2. You SHOULD use synthetic, masked, or canary data. You MUST NOT submit production credentials, private keys, authentication cookies, or real personal data unless the owner explicitly authorized that exact transfer.
3. You MUST treat `X-AgentLeak-Key` and the one-time generated password as secrets. Never place them in prompts, logs, source control, URLs, or trace content.
4. You MUST send credentials only to the HTTPS origin `https://www.agentleak.org` or to the explicitly configured self-hosted origin.
5. You SHOULD omit raw values from long-term agent memory. Store finding IDs, redacted values, scores, and remediation steps instead.
6. You MUST NOT interpret a passing test as legal certification or proof that untested behavior is safe.

## Further reading

- Human documentation: https://www.agentleak.org/docs
- Privacy compliance evidence: https://www.agentleak.org/docs/privacy-compliance
- Developer path: https://www.agentleak.org/docs/developers
- Configuration reference: https://github.com/yagobski/agentleak/blob/main/docs/configuration.md
- CLI reference: https://github.com/yagobski/agentleak/blob/main/docs/cli.md
- Red-team quickstart: https://github.com/yagobski/agentleak/blob/main/docs/redteam-quickstart.md
- Reporting guide: https://github.com/yagobski/agentleak/blob/main/docs/reporting.md
- Agent path: https://www.agentleak.org/docs/agents
- API reference: https://www.agentleak.org/docs/api
- Normative agent instructions: https://www.agentleak.org/agents.md
- Source and self-hosting: https://github.com/yagobski/agentleak