Agents

Drive Pictograph from Claude, OpenAI, or any framework that speaks JSON Schema. One registry, three integration paths.

Every Pictograph operation is exposed as both a typed Python SDK call and an agent tool. The 28-tool registry feeds three integration paths.

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.

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:

pip install 'pictograph[agents]'

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 · OpenAI.

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:

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:

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 for end-to-end examples.

What’s in the registry

Twenty-eight tools, grouped by category. Full JSON schemas at /docs/api-reference/tools.

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.

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.