Agents API

Create and run agents with the Agents API, with the parameters, request bodies and responses of each endpoint and the scopes they require.

An agent is a saved AI configuration: a system prompt, a model and an optional output schema. Workflows use agents in the AI Agent block. These endpoints manage your company's custom agents and run them outside a workflow.

Scope	Endpoints
`workflows:read`	List, get, list executions
`workflows:write`	Create, update, delete
`workflows:execute`	Test, execute

Core agents

Loopfour provides built-in core agents to every company. They can be read and used in an AI Agent step, but not changed, deleted or run through this API.

ID	Name	Type
`agent_extraction`	Universal Extraction Agent	`extraction`
`agent_content`	Content Generation Agent	`content`
`agent_transform`	Data Transformation Agent	`transform`
`agent_decision`	Decision & Routing Agent	`decision`

Agent object

Field	Type	Meaning
`id`	string	Agent ID. Core agents use the IDs above
`name`	string	1 to 255 characters, unique within your company
`description`	string or null	Up to 1,000 characters
`type`	string	`extraction`, `decision`, `content`, `transform`, `code`, `classification` or `custom`
`provider`	string	`openai` or `anthropic`
`model`	string	`gpt-5.6-sol` (with `openai`) or `claude-opus-5` (with `anthropic`)
`status`	string	`active` or `deprecated`
`version`	integer	Goes up by 1 on each update
`scope`	string	`global` for core agents, `company` for yours
`isBuiltIn`	boolean	`true` for core agents

Get also returns the prompt and generation settings.

List agents

GET /api/v1/agents

Query parameter	Type	Default	Meaning
`type`	string		An agent type
`status`	string		`active` or `deprecated`
`search`	string		Match on the name
`includeBuiltIn`	boolean	`false`	Put the core agents at the start of the first page
`limit`	integer	20	1 to 100
`cursor`	string		`meta.cursor` from the previous page

curl 'https://workflow.loopfour.ai/api/v1/agents?type=extraction&includeBuiltIn=true' \
  -H 'x-api-key: wfk_live_your_api_key'

Create an agent

POST /api/v1/agents

Field	Type	Required	Meaning
`name`	string	Yes	1 to 255 characters. A name already used in your company returns `400`
`type`	string	Yes	An agent type
`systemPrompt`	string	Yes	1 to 50,000 characters
`description`	string	No	Up to 1,000 characters
`provider`	string	No	Default `openai`
`model`	string	No	Default `gpt-5.6-sol`. Must match the provider
`userPrompt`	string	No	Up to 50,000 characters
`outputSchema`	object	No	JSON Schema for structured output
`temperature`	number	No	0 to 2, default 0.7
`maxTokens`	integer	No	1 to 128,000, default 4096
`topP`	number	No	0 to 1

curl -X POST 'https://workflow.loopfour.ai/api/v1/agents' \
  -H 'x-api-key: wfk_live_your_api_key' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Vendor bill extractor",
    "type": "extraction",
    "provider": "anthropic",
    "model": "claude-opus-5",
    "systemPrompt": "Extract the vendor name, bill number, bill date, due date and total from the vendor bill text.",
    "outputSchema": {
      "type": "object",
      "properties": {
        "vendorName": { "type": "string" },
        "billNumber": { "type": "string" },
        "billDate": { "type": "string" },
        "dueDate": { "type": "string" },
        "total": { "type": "number" }
      },
      "required": ["vendorName", "total"]
    },
    "temperature": 0
  }'

The response is 201 with the new agent. A provider and model that do not pair return 400.

Get an agent

GET /api/v1/agents/{id}

id is a custom agent ID or a core agent ID such as agent_extraction.

Update an agent

PUT /api/v1/agents/{id}

Send any of the create fields. Each update raises version by 1. Core agents and agents of another company return 400 (Cannot modify built-in agents, Cannot modify agents not owned by your company).

Delete an agent

DELETE /api/v1/agents/{id}

Marks a custom agent deprecated. The response is { "deleted": true }. Core agents return 400.

Test an agent

POST /api/v1/agents/{id}/test

Field	Type	Required	Meaning
`input`	object	Yes	Input variables for the prompt
`userMessage`	string	No	Message to send

Runs a custom agent once and records the execution. For a core agent the response is a message that core agents can be tested only in a workflow.

Execute an agent

POST /api/v1/agents/{id}/execute

Field	Type	Required	Meaning
`input`	object	Yes	Input variables for the prompt
`userMessage`	string	No	Message to send
`workflowRunId`	string (UUID)	No	Link the execution to a run
`overrides`	object	No	`temperature`, `maxTokens`, `model`, `customInstructions` (up to 10,000 characters) and `examples` (up to 10) for this execution only

curl -X POST 'https://workflow.loopfour.ai/api/v1/agents/7c9e6679-7425-40de-944b-e07fc1f90ae7/execute' \
  -H 'x-api-key: wfk_live_your_api_key' \
  -H 'Content-Type: application/json' \
  -d '{ "input": {}, "userMessage": "Bill INV-2291 from Acme Supplies, dated 2026-02-01, due 2026-03-03, total 4,180.00" }'

{
  "success": true,
  "data": {
    "executionId": "1b4e28ba-2fa1-41d2-883f-0016d3cca427",
    "status": "completed",
    "output": {
      "vendorName": "Acme Supplies",
      "billNumber": "INV-2291",
      "billDate": "2026-02-01",
      "dueDate": "2026-03-03",
      "total": 4180
    },
    "content": "...",
    "usage": { "promptTokens": 412, "completionTokens": 58, "totalTokens": 470 },
    "cost": { "inputCost": 0.0021, "outputCost": 0.0015, "totalCost": 0.0036, "currency": "USD" },
    "latencyMs": 1830,
    "model": "claude-opus-5",
    "provider": "anthropic"
  }
}

output is the structured result when the agent has an outputSchema, otherwise { "content": "..." }. A core agent returns 400 BUILT_IN_AGENT. A model failure returns 500 AGENT_EXECUTION_ERROR with error.executionId.

List executions

GET /api/v1/agents/{id}/executions

Takes limit (default 20, maximum 100) and cursor. Each entry has id, status, input, output, error, usage, estimatedCost, latencyMs, model, provider, workflowRunId and createdAt.

Errors

Status	Code	Cause
`400`	`BAD_REQUEST`	Duplicate name, unsupported provider and model pair, or a change to a core or another company's agent
`400`	`BUILT_IN_AGENT`	Execute called on a core agent
`400`	`ZodError` in `error.name`	Body or query does not match the schema
`401`	`UNAUTHORIZED`	Missing or invalid API key
`403`	`FORBIDDEN`	Key lacks the scope
`404`	`NOT_FOUND`	Agent not found
`500`	`AGENT_EXECUTION_ERROR`	The model call failed

Agents API

On this page