Ctrlk
ResourcesDocsSign InBook a DemoGet Started
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Roboflow Agent

The in-app Roboflow Agent that builds, runs, and debugs Workflows and Rapid models, plus its HTTP chat API.

About

Roboflow Agent has access to your Workspace and can create, edit, run, and debug Workflows. You can also use it to set up Rapid models. Access the Agent by clicking "Agent" in the left sidebar of your workspace.

Capabilities

The Agent can work with:

Background Tasks

Long jobs the Agent starts keep running while you chat: model training, auto-labeling, dataset version generation, project merges, class remaps, split rebalances, and Batch Processing jobs. A pill above the chat box counts the running ones. Click it, or click "Background Tasks" in the left menu, to open a panel that lists them under "Running" and "Finished". Click a task to open the page it created.

The Agent tells you in the chat when a task finishes, even if you closed the tab and came back later. Only jobs started from inside a conversation appear here. A training you start elsewhere in the app or through the API does not, and you track it in the Activity Center instead.

HTTP API

The Agent API lets you interact with the Roboflow AI agent through api.roboflow.com. You can send natural-language instructions to create or edit Workflows, then publish them when ready. All edits are saved as drafts until you explicitly publish.

Authentication is via API key. If you use a Scoped API Key with folder restrictions, the agent will only be able to access Workflows and models within that folder scope, and it will not see projects that sit outside a folder. Asking the agent to list workspace models returns only the models the caller can already see.

Chat

Send a message to the agent. Start a new conversation, or continue one by passing conversation_id.

Chat with the agent

post

Send a message to the agent. The agent can create new Workflows, edit existing ones, and answer questions about your workspace. Workflow changes are saved as drafts. Requires the workflow:create and workflow:update scopes.

Path parameters
workspacestringRequired

Workspace URL slug.

Example: my-workspace
Body
api_keystringRequired

Workspace API key.

messagestringRequired

The instruction or question for the agent.

Example: Build me a workflow that detects cars and counts them
conversation_idstringOptional

ID of an existing conversation to continue. Omit to start a new conversation.

Example: conv_xyz789
modestring · enumOptional

agent (default) makes changes. In plan mode the agent outlines what it would do without making changes.

Default: agentPossible values:
Responses
200

The agent's reply.

application/json
textstringOptional

The agent's response text.

Example: I created a workflow called 'Car Counter' that detects and counts cars.
conversation_idstringOptional

The conversation ID. Pass it back in later requests to continue the conversation.

Example: conv_xyz789
post/{workspace}/agent/chat
POST /{workspace}/agent/chat HTTP/1.1
Host: api.roboflow.com
Content-Type: application/json
Accept: */*
Content-Length: 131

{
  "api_key": "text",
  "message": "Build me a workflow that detects cars and counts them",
  "conversation_id": "conv_xyz789",
  "mode": "agent"
}
{
  "text": "I created a workflow called 'Car Counter' that detects and counts cars.",
  "workflows": [
    {
      "id": "wf_abc123",
      "name": "Car Counter",
      "url": "car-counter",
      "specification": {}
    }
  ],
  "conversation_id": "conv_xyz789"
}

Publish a Workflow

Deploy the latest draft of a Workflow the agent created or edited.

Publish a Workflow

post

Deploy the latest draft version of a Workflow that the agent created or edited. Returns 400 if there is no unpublished draft. Requires the workflow:update scope.

Path parameters
workspacestringRequired

Workspace URL slug.

Example: my-workspace
workflowUrlstringRequired

Workflow URL slug.

Example: car-counter
Query parameters
api_keystringRequired

Workspace API key.

Responses
200

The draft was published.

application/json
workflowIdstringOptionalExample: wf_abc123
workflowUrlstringOptionalExample: car-counter
versionIdstringOptionalExample: v-1700000000
statusstringOptionalExample: published
post/{workspace}/agent/workflows/{workflowUrl}/publish
POST /{workspace}/agent/workflows/{workflowUrl}/publish?api_key=text HTTP/1.1
Host: api.roboflow.com
Accept: */*

{
  "workflowId": "wf_abc123",
  "workflowUrl": "car-counter",
  "versionId": "v-1700000000",
  "status": "published"
}

List Conversations

List conversations

get

Return all agent conversations in the workspace. Requires the workflow:read scope.

Path parameters
workspacestringRequired

Workspace URL slug.

Example: my-workspace
Query parameters
api_keystringRequired

Workspace API key.

sourcestring · enumOptional

Filter by origin: api or web.

Possible values:
workflowstringOptional

Filter by Workflow URL slug. Only returns conversations that reference this Workflow.

Responses
200

The workspace's conversations.

application/json
get/{workspace}/agent/conversations
GET /{workspace}/agent/conversations?api_key=text HTTP/1.1
Host: api.roboflow.com
Accept: */*

{
  "conversations": [
    {
      "id": "conv_xyz789",
      "name": "Car Counter",
      "source": "api",
      "workflowIds": [
        "wf_abc123"
      ],
      "created_on": "2026-05-14T20:00:00.000Z",
      "updated_on": "2026-05-14T20:05:00.000Z"
    }
  ]
}

Get a Conversation

Get a conversation

get

Return the full conversation including all messages. Requires the workflow:read scope.

Path parameters
workspacestringRequired

Workspace URL slug.

Example: my-workspace
idstringRequired

Conversation ID.

Example: conv_xyz789
Query parameters
api_keystringRequired

Workspace API key.

Responses
200

The conversation with its messages.

application/json
idstringOptionalExample: conv_xyz789
namestringOptionalExample: Car Counter
sourcestring · enumOptional

Where the conversation started: api or web.

Example: apiPossible values:
workflowIdsstring[]Optional

IDs of Workflows referenced by the conversation.

Example: ["wf_abc123"]
created_onstring · date-timeOptionalExample: 2026-05-14T20:00:00.000Z
updated_onstring · date-timeOptionalExample: 2026-05-14T20:05:00.000Z
typestringOptionalExample: agent
get/{workspace}/agent/conversations/{id}
GET /{workspace}/agent/conversations/{id}?api_key=text HTTP/1.1
Host: api.roboflow.com
Accept: */*

{
  "id": "conv_xyz789",
  "name": "Car Counter",
  "source": "api",
  "workflowIds": [
    "wf_abc123"
  ],
  "created_on": "2026-05-14T20:00:00.000Z",
  "updated_on": "2026-05-14T20:05:00.000Z",
  "type": "agent",
  "messages": [
    {
      "id": "msg_1",
      "role": "user",
      "parts": [
        {
          "type": "text",
          "text": "Build me a workflow that detects cars"
        }
      ]
    }
  ]
}

MCP Server

Connect your AI agent to the MCP Server and it can hand work to Roboflow Agent with these tools:

Tool
Description

agent_chat

Chat with the Roboflow AI agent.

agent_chat_result

Collect the result of a run that was still working.

agent_conversations_list

List agent conversations in the workspace.

agent_conversation_get

Get one conversation with its message history.

agent_workflow_publish

Publish the latest agent-edited draft of a Workflow.

PreviousMCP Server
NextWorkspaces

Last updated

Was this helpful?