---
title: Agents
description: Drive Pictograph from Claude, OpenAI, or any framework that speaks JSON Schema. One registry, three integration paths.
section: Agents
order: 0
---
Every Pictograph operation is exposed as both a typed Python SDK call and an agent tool. The 28-tool registry feeds three integration paths.

```python
from pictograph.agents import create_toolkit

toolkit = create_toolkit()  # reads PICTOGRAPH_API_KEY
```

## Three integration paths

### Bundled adapters — Claude / OpenAI

For raw tool-use loops against the Anthropic or OpenAI SDKs, the adapters return ready-to-pass tool dicts. No extra dependencies.

```python
from pictograph.agents import for_anthropic_messages, for_openai_responses

claude_tools = for_anthropic_messages(toolkit)   # → anthropic.messages.create(tools=...)
openai_tools = for_openai_responses(toolkit)     # → openai.responses.create(tools=...)

# Both paths dispatch results the same way:
result = toolkit.dispatch(name="list_datasets", args={"limit": 10})
```

For the framework SDKs (`claude-agent-sdk`, `openai-agents`) install the extra:

```bash
pip install 'pictograph[agents]'
```

```python
from pictograph.agents import for_claude_agent_sdk, for_openai_agents

claude_sdk_tools = for_claude_agent_sdk(toolkit)   # @tool-decorated callables
openai_sdk_tools = for_openai_agents(toolkit)      # FunctionTool objects
```

Full integration cookbooks: [Claude](/docs/agents/claude.md) · [OpenAI](/docs/agents/openai.md).

### Bundled Claude Skill

The SDK ships a Claude Skill (`pictograph-cv`) with workflow recipes, reference docs, and bash-callable Python scripts. Install it once and Claude auto-discovers it:

```bash
pictograph agents install-skill --target claude-code   # → ~/.claude/skills/pictograph-cv/
pictograph agents install-skill --target claude-ai     # → ./pictograph-cv.zip (upload at claude.ai/skills)
pictograph agents install-skill --target both
```

Update the skill after upgrading the SDK by re-running the install command (it overwrites the existing directory).

### Dynamic discovery — `tools.json`

For frameworks without a bundled adapter (Vercel AI SDK, LangChain, custom dispatchers), fetch the JSON Schema registry directly:

```bash
curl -H "X-API-Key: pk_live_…" https://api.pictograph.io/api/v1/developer/tools.json
```

Each entry has `name`, `description`, `input_schema`, plus metadata (`required_role`, `credit_cost`, `idempotent`). Wire it into your dispatcher and route the model's tool calls to the matching SDK method. See [Dynamic discovery](/docs/agents/dynamic-discovery.md) for end-to-end examples.

## What's in the registry

Twenty-eight tools, grouped by category. Full JSON schemas at [`/docs/api-reference/tools`](/docs/api-reference/tools.md).

| Category | Tools |
| --- | --- |
| Workflows | `upload_dataset_from_folder`, `auto_annotate_dataset`, `train_pipeline`, `full_pipeline` |
| Datasets | `list_datasets`, `get_dataset`, `create_dataset`, `delete_dataset` |
| Images | `upload_image`, `delete_image` |
| Annotations | `get_annotations`, `save_annotations` |
| Auto-annotate | `auto_annotate_point`, `auto_annotate_box`, `auto_annotate_text` |
| Search | `search_by_tag`, `search_by_similarity` |
| Exports | `create_export`, `list_exports`, `download_export` |
| Training | `get_training_status`, `cancel_training` |
| Models | `list_models`, `download_model` |
| Credits | `get_credit_balance`, `estimate_credit_cost` |
| Connectors | `validate_connector`, `import_from_connector` |

## Guardrails

The toolkit enforces three guardrails on every dispatch, independent of which integration path you use.

**Role gate (`required_role`)** — each tool's required role is metadata in the registry, but the API re-checks the calling key's role on every request. An agent holding a `viewer` key gets `403 ForbiddenError` on any write tool.

**Credit gate (`credit_cost`)** — paid tools (`auto_annotate_dataset`, `train_pipeline`, `full_pipeline`) have known costs. Agents can pre-flight via `get_credit_balance` + `estimate_credit_cost` (both in the registry) and refuse to start when the balance is short.

**Response cap (`max_response_tokens`)** — large list/get results that exceed the cap (default 25k tokens) are truncated with a `_truncated` marker. The agent re-calls with narrower filters. Pass `max_response_tokens=N` to `create_toolkit(...)` to override.

## Recommended system prompt patterns

These three rules keep agents safe and cheap. Drop them into your system prompt.

```text
1. Before destructive actions (delete_dataset, delete_image,
   cancel_training), restate exactly what will be removed and ask
   for confirmation.

2. Before paid actions (auto_annotate_dataset, train_pipeline,
   full_pipeline), call estimate_credit_cost first, then surface
   the cost and the remaining balance. Proceed only if sufficient.

3. For multi-step tasks, prefer the workflow tools (full_pipeline,
   upload_dataset_from_folder, auto_annotate_dataset, train_pipeline)
   over chaining individual resource tools. They handle short-circuit
   on failure and credit gating automatically.
```

## See also

- [Claude](/docs/agents/claude.md) · [OpenAI](/docs/agents/openai.md) — integration cookbooks
- [Dynamic discovery](/docs/agents/dynamic-discovery.md) — for framework-agnostic stacks
- [Cookbook](/docs/agents/cookbook.md) — recipe-style end-to-end examples
- [Tool reference](/docs/api-reference/tools.md) — full JSON schemas for all 28 tools