> ## Documentation Index
> Fetch the complete documentation index at: https://docs.argil.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Build an agent

> Give an agent built on the Anthropic, OpenAI or xAI APIs, or on an agent framework, access to Argil.

Model APIs call remote MCP servers for you: pass Argil's URL and an API key, and the model uses Argil's tools within one request. Agent frameworks connect as MCP clients in your process.

Create a dedicated API key per agent in [**Workspace settings → API keys**](https://www.argil.ai/workspace-settings?tab=api-keys), so you can revoke one without touching the others.

> [tab] Anthropic API
>
> ```python theme={null}
> import os, anthropic
>
> client = anthropic.Anthropic()
> message = client.beta.messages.create(
>     model="claude-sonnet-5-5",
>     max_tokens=4096,
>     betas=["mcp-client-2025-11-20"],
>     mcp_servers=[{
>         "type": "url",
>         "url": "https://mcp.argil.ai/mcp",
>         "name": "argil",
>         "authorization_token": os.environ["ARGIL_API_KEY"],
>     }],
>     tools=[{"type": "mcp_toolset", "mcp_server_name": "argil"}],
>     messages=[{"role": "user", "content": "Make a square product shot of a glass perfume bottle on black velvet. Spend at most 5 credits."}],
> )
> ```

> [tab] OpenAI API
>
> ```python theme={null}
> import os
> from openai import OpenAI
>
> client = OpenAI()
> response = client.responses.create(
>     model="gpt-6",
>     tools=[{
>         "type": "mcp",
>         "server_label": "argil",
>         "server_url": "https://mcp.argil.ai/mcp",
>         "authorization": os.environ["ARGIL_API_KEY"],
>         "require_approval": "never",
>     }],
>     input="Make a square product shot of a glass perfume bottle on black velvet. Spend at most 5 credits.",
> )
> ```
>
> `require_approval: "never"` runs tools without a round trip to your code. Keep a budget in the prompt, or add your own approval step.

> [tab] xAI API
>
> ```python theme={null}
> import os
> from openai import OpenAI
>
> client = OpenAI(api_key=os.environ["XAI_API_KEY"], base_url="https://api.x.ai/v1")
> response = client.responses.create(
>     model="grok-4.7",
>     tools=[{
>         "type": "mcp",
>         "server_label": "argil",
>         "server_url": "https://mcp.argil.ai/mcp",
>         "authorization": os.environ["ARGIL_API_KEY"],
>     }],
>     input="Make a square product shot of a glass perfume bottle on black velvet. Spend at most 5 credits.",
> )
> ```
>
> The xAI API runs tools without asking: keep a budget in the prompt.

> [tab] OpenAI Agents SDK
>
> ```python theme={null}
> import os
> from agents import Agent, Runner
> from agents.mcp import MCPServerStreamableHttp
>
> async with MCPServerStreamableHttp(
>     name="argil",
>     params={
>         "url": "https://mcp.argil.ai/mcp",
>         "headers": {"Authorization": f"Bearer {os.environ['ARGIL_API_KEY']}"},
>         "timeout": 60,
>     },
>     cache_tools_list=True,
> ) as argil:
>     agent = Agent(name="Creative", instructions="You make ad creatives with Argil.", mcp_servers=[argil])
>     result = await Runner.run(agent, "Three 9:16 hooks for a running shoe, 5 seconds each, at most 25 credits each.")
> ```

> [tab] Vercel AI SDK
>
> ```ts theme={null}
> import { createMCPClient } from "@ai-sdk/mcp";
> import { generateText, stepCountIs } from "ai";
> import { anthropic } from "@ai-sdk/anthropic";
>
> const argil = await createMCPClient({
>   transport: {
>     type: "http",
>     url: "https://mcp.argil.ai/mcp",
>     headers: { Authorization: `Bearer ${process.env.ARGIL_API_KEY}` },
>   },
> });
>
> const { text } = await generateText({
>   model: anthropic("claude-sonnet-5-5"),
>   tools: await argil.tools(),
>   stopWhen: stepCountIs(12),
>   prompt: "Make a square product shot of a glass perfume bottle on black velvet. Spend at most 5 credits.",
> });
> await argil.close();
> ```

## Design rules for a media agent

1. **Send an idempotency key.** Have the agent pass a new UUID as `idempotency_key` for each generation it means to make, and the same one when it retries. A retry then returns the generation already started instead of paying for a second one.
2. **Give it a budget.** "At most N credits each" becomes `max_credits`: Argil refuses anything above it, before spending.
3. **Let it wait, in steps.** A call returns within about 40 seconds. A video comes back as `processing`, and the agent checks again with `get_generation`. Allow enough steps: a 4-minute video takes about 6 checks.
4. **Tag what it makes.** `metadata` (for example `{"sku": "A-102"}`) lets it find generations later with `list_generations`.
5. **Don't make the model wait on a batch.** For many generations, start them all, then let a webhook endpoint (`create_webhook_endpoint`) tell your server when each one finishes.

See [How it works](https://docs.argil.ai/v2/mcp/how-it-works.md) for the details behind these rules.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.