---
title: "Run a stateless AI agent with tools"
method: POST
path: "/api/ai/{project_id}/agent"
tags: ["AI"]
---

# Run a stateless AI agent with tools

`POST /api/ai/{project_id}/agent`

## Request

- Base URL: `https://core.blink.new`
- URL: `https://core.blink.new/api/ai/{project_id}/agent`
- Auth: HTTP bearer

**🤖 AI Agent with Tool Use**

Run an AI agent that autonomously uses built-in tools and external webhooks
in a loop until a stop condition is met.

**🔧 Built-in Tools** (specify names in `agent.tools`)
- `web_search` – real-time web search
- `fetch_url` – HTTP fetch any URL
- `run_code` – execute code in a sandbox
- `rag_search` – search project knowledge base
- `generate_image` / `edit_image` – AI image generation
- `generate_video` / `image_to_video` – AI video generation
- `db_insert/list/get/update/delete` – database CRUD operations
- `storage_upload/download/list/delete` – file storage operations

Custom webhook tools call your own HTTPS endpoints; each request is signed (Standard Webhooks headers) with the project's webhook signing secret.

**📱 Client Tools**
- Define tools executed on the client side (streaming mode only)
- Tool calls are forwarded in the SSE stream; client sends results back

**📡 Streaming**
- Set `stream: true` to receive a Vercel AI SDK data stream (SSE)
- Includes tool calls and results as they occur in real time

## Path parameters

- `project_id` string, required

## Request body

- object
  - `stream` boolean, required: Enable SSE streaming of agent steps and tool calls
  - `prompt` string: Single-turn prompt (headless mode). Mutually exclusive with `messages`.
  - `messages` object[]: Conversation history (UI mode). Mutually exclusive with `prompt`.
    - `role` 'user' | 'assistant' | 'system'
    - `content` string
    - `parts` object[]: Message parts for tool invocations
    - `id` string
  - `agent` object, required: Agent configuration
    - `model` string, required: AI model identifier in provider/model-id format
    - `system` string: System prompt for the agent
    - `tools` string[]: Allowlist of built-in tool names to enable
    - `webhook_tools` object[]: Custom tools that call external HTTPS endpoints
      - `name` string, required
      - `description` string, required
      - `input_schema` object, required: JSON Schema for the tool's input parameters
      - `webhook_url` string, uri, required
    - `client_tools` object[]: Tools executed on the client side (streaming only)
      - `name` string, required
      - `description` string, required
      - `input_schema` object, required
    - `tool_choice` 'auto' | 'required' | 'none': How the agent selects which tools to use
    - `stop_when` object[]: Conditions to stop the agent loop
      - `type` 'step_count_is'
      - `count` integer
  - `sandbox_id` string: Optional sandbox ID for sandbox filesystem tools

## Response `200`

Agent execution successful

- object
  - `text` string: Final text output from the agent
  - `finishReason` 'stop' | 'length' | 'tool-calls' | 'error' | 'content-filter': Why the agent stopped
  - `steps` object[]: Each step in the agent's reasoning loop
    - `text` string
    - `toolCalls` object[]
      - `toolCallId` string
      - `toolName` string
      - `args` object
    - `toolResults` object[]
      - `toolCallId` string
      - `result` object
    - `finishReason` string
    - `usage` object
      - `inputTokens` integer
      - `outputTokens` integer
  - `usage` object: Total token usage across all steps
    - `inputTokens` integer
    - `outputTokens` integer
    - `totalTokens` integer
  - `_billing` object: Blink billing information
    - `model` string
    - `creditsCharged` number
    - `costUSD` number
    - `breakdown` object
      - `ai` object
        - `credits` number
        - `costUSD` number
      - `tools` object

## Other responses

- `400`: Invalid request (`VALIDATION_FAILED`, `INVALID_PROJECT_ID`, `INVALID_ARGUMENTS`), or, when zero data retention is enabled for AI requests, the model cannot run under it (`MODEL_NOT_ZDR_ELIGIBLE`).
- `401`: Authentication required or invalid API key
- `403`: Project ID mismatch or insufficient permissions
- `500`: Internal server error

---

[API](https://skmtc.dev/blink/apis/blink-apis.md) - [All operations](https://skmtc.dev/blink/apis/blink-apis/llms.txt) - [OpenAPI document](https://skmtc.dev/blink/apis/blink-apis/revisions/4c59c706078e?raw)