The Agent — a job description

Think: hiring paperwork

An Agent is who the worker is and what tools the role is allowed to touch. Same Agent can be hired into many jobs — the description doesn't change between shifts.

Label: create an agent

curl -X POST https://api.anthropic.com/v1/agents \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2026-04-01" \
  -H "content-type: application/json" \
  -d '{
    "name": "social-asset-generator",
    "model": {"id": "claude-opus-4-7"},
    "system": "You draft social posts...",
    "tools": [{"type": "agent_toolset_20260401"}]
  }'

One Agent definition, versioned and reused. The brain, separated from any single task.

The Environment — a private office

Think: a clean desk in a locked room

A pre-built workspace with the right software already installed and locked doors to systems the worker shouldn't touch. Same room shape, fresh for every workday.

Label: create an environment

curl -X POST https://api.anthropic.com/v1/environments \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2026-04-01" \
  -H "content-type: application/json" \
  -d '{
    "os": "ubuntu-22.04",
    "packages": ["python3.12", "pandas2.2.0"],
    "networking": "limited",
    "allowed_hosts": ["api.internal-data.com"]
  }'

A reproducible container — secure, isolated, predictable. Your core systems stay untouched.

The Session — a workday

Think: a desk that remembers

A worker clocks in, does the job, takes a break — and when they return, the papers are still on the desk. Sessions checkpoint when idle and resume exactly where they left off.

Label: start a session

curl -X POST https://api.anthropic.com/v1/sessions \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2026-04-01" \
  -d '{"agent_id": "agt_...", "environment_id": "env_..."}'

# send a message
curl -X POST https://api.anthropic.com/v1/sessions/$ID/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -d '{"content": "Draft next weeks campaign."}'

# container checkpoints on idle. resume tomorrow.

Long jobs don't need to fit in one conversation. State survives sleep.

Skills — a table of contents, not a textbook

Think: scanning the index

Skills are folders of expertise. The agent scans the titles, opens only the chapters it needs, ignores the rest. The whole library is available; the context window stays light.

Label: attach a skill

curl -X PATCH https://api.anthropic.com/v1/agents/$AGENT_ID \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2026-04-01" \
  -d '{
    "version": 3,
    "skills": [
      {"type": "anthropic", "skill": "docx"},
      {"type": "custom", "skill_id": "skl_brand_voice"}
    ]
  }'

Progressive disclosure: load on demand, not all at once. Deep expertise without token bloat.

Vaults — a safe deposit box

Think: the lock vs the key

The Agent knows the shape of the lock — it knows it needs Slack. The Session brings the user's actual key. Build the product once; serve thousands of users without ever co-mingling their credentials.

Label: store a credential, then use it

# store the user's credential in a vault
curl -X POST https://api.anthropic.com/v1/vaults/$VAULT_ID/credentials \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -d '{"name": "slack_oauth", "value": "xoxb-..."}'

# attach it at session creation — agent never sees the secret
curl -X POST https://api.anthropic.com/v1/sessions \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -d '{"agent_id": "agt_...", "vault_ids": ["vlt_steve_slack"]}'

Manage your product at the agent level. Manage your users at the session level.

Outcomes — replace the back-and-forth

Direct prompt

You ask. It answers. You read it, decide if it's right, and re-ask until it is.

You are the grader. You can't go to dinner.

Outcome

You state the rubric once. An independent grader checks each draft and sends it back until it passes.

You read the final draft only.

Label: define an outcome

curl -X POST https://api.anthropic.com/v1/sessions/$ID/outcomes \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2026-04-01" \
  -d '{
    "rubric": "10 LinkedIn posts. Each under 280 chars. Each ends with a question.",
    "max_iterations": 5
  }'
# returns: status = satisfied | needs_revision | max_iterations_reached

Conversation becomes work the moment you can name "done."

Webhooks — call me when it's done

Think: a tap on the shoulder

You don't sit and wait. You hand off the job, go to dinner, and the agent calls you back when the artifact is ready. Hours of work happen in the background.

Label: register a webhook + receive it

# tell the platform where to call you
curl -X POST https://api.anthropic.com/v1/webhooks \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -d '{"url": "https://yourapp.com/hook", "events": ["session.outcome.satisfied"]}'

# later, you receive:
# POST https://yourapp.com/hook
# { "id": "evt_...", "type": "session.outcome.satisfied", "session_id": "sess_..." }
# fetch the artifact with a GET on receipt.

Long jobs no longer block humans. Work that finishes itself.

Steve ships a week of campaigns over the weekend

The human story

• Friday 5:30pm — Steve kicks off the agent: "Draft next week's launch posts for LinkedIn, X, and Instagram."
• 5:35pm — He closes his laptop and goes home for the weekend.
• Monday 8:00am — His phone buzzes. The agent is done.
• 8:10am — He reviews 15 posts and 5 images. Approves them. Coffee.

Under the hood

• POST /sessions with the social-asset-generator agent
• Session checkpoints when Steve disconnects
• Grader returns satisfied on iteration 3
• Webhook fires; Steve gets the artifact link

The agent worked most of the weekend. Steve worked ten minutes.

Social Asset Generator — the full template

Label: social-asset-generator.yaml

name: Social asset generator
model: claude-sonnet-4-6
system: |
  You draft a week of social posts
  across LinkedIn, X, and Instagram
  with images and schedules them.

  1. Read the brand brief
  2. Draft posts per platform tone
  3. Generate images in Figma
  4. Schedule via Buffer
  5. Notify the team in Slack
mcp_servers:
  - figma
  - buffer
  - slack
tools:
  - agent_toolset_20260401

Why this template

claude-sonnet-4-6 — fast and cost-effective. This work is volume, not depth.

Three MCP servers — the toolbelt is the whole point. Each one is a tab a marketer would otherwise switch between.

Numbered system prompt — five clear steps. The agent has a playbook, not a vibe.

Clone it. Swap Buffer for your scheduler. Ship Monday.