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:
Workflows: build from a plain description, run on images, RTSP streams, video, your browser webcam, or your phone camera, run only the part of a video you ask for, watch live previews, auto-fix failures, investigate run errors, and draw detection zones. To add a camera, pick "Webcam", "Network Streams", or "Phone" when the Agent asks. A webcam or phone stream stops when its browser session ends.
Attached media: analyze images and MP4 or MOV videos you drop into the chat, and build and verify Workflows with them.
Image generation: create 1 to 10 images from a text description when you have no photos yet. The Agent starts when you ask it to generate. Ask for a price first if you want an estimate. Each image is saved to your Asset Library, and you pay only for the images that are saved. The Agent cannot use your own images as a reference.
Rapid models: set up, manage, and diagnose training failures.
Workflow Evals: create an Eval, review and approve ground truth in the chat, run and compare Workflows, and explain the results. The Agent asks before it starts a Run that costs credits. It can save the best Workflow as an unpublished draft.
Projects: create projects, start model training, rebalance splits, and merge projects.
Universe datasets: find public datasets on Universe, compare them, and copy a whole dataset or a set number of images into a project. You agree on sources, image counts, and class changes in the chat before the Agent copies anything.
Datasets: browse images by labeling stage, add workspace images to a model and start labeling them, send a batch to review or back for edits, approve or reject images in Review (after you confirm the jobs and image count), accept images into the dataset, and return work to unassigned.
Batch Processing: run a published Workflow over images in your Asset Library, set up a new job with you in the chat, list your jobs, and report the status of one.
Active Learning: turn collection on or off per project and edit its limits and conditions.
Vision Events: add blocks to Workflows, answer questions about your event data, and schedule Summary Reports.
Usage: show your Credit Usage Dashboard with filters matching your question.
Edge devices: answer questions with read-only access to your Deployment Manager fleet, telemetry, logs, and streams.
Tabs: organize open Workflows, models, projects, and usage views; drag to reorder; reopen closed items or create new ones from the "+" tab.
Publish Workflows
Whether the Agent's edits go live depends on the Workflow's publishing mode. In "Auto-Publish" mode, every save publishes, so a new Workflow is live right away. In "Manual Publish" mode, the Agent's edits are saved as drafts and do not change the live Workflow.
To make a saved draft live, find the Workflow in the asset bar above the chat box. An "Action needed" chip shows when a Workflow has saved changes that are not live. Click "Publish" to update the live Workflow, or "Publish as a Copy" to publish the draft as a new Workflow and keep the original unchanged. Click "Dismiss" to keep the draft without publishing. You need permission to publish Workflows and write access to the Workflow's folder.
To use a published Workflow in your code, ask the Agent for help. It asks if you want a "Quick API Call" or a "Coding Agent". Pick "Quick API Call" to get a code snippet in the chat. Pick "Coding Agent" to get a "Deploy With Coding Agent" card. Click the card to open a prompt that you copy into your coding agent. If the Workflow has changes that are not live, the Agent asks you to publish them first.
Add Media
Drop files anywhere in the chat to give them to the Agent. You can also paste them, or click the paperclip in the chat box and pick "Attach Files" or "Attach Folder". On the home page, click "+" and pick "Attach Files". Folders expand into the files inside them. A zip file expands only when you drop it, up to 300 files. For a larger zip, use the Upload Data page.
To take photos, interval frames, or an MP4 clip with your webcam, click the paperclip or "+" and pick "Use Camera". When the Agent asks for media, its request also has a "Use Camera" button. After you record a clip, click "Keep Video". Then click the add button (ex: "Add 3 to Message", "Add Video to Message") to attach the captures to your next message.
The upload starts when you send the message and runs in the background, so you can keep chatting. A card in the chat shows the progress and a "Cancel" button, and the upload also appears in the Background Tasks panel. Images and videos go to your Asset Library.
Uploads with annotation files, or with images in two or more folders, wait for a destination instead of starting right away. The Agent sends them to a model or your Workspace, and asks first if your message leaves the destination open. In a model, folder names (ex: train, valid, test) set the splits. Files with no split from their folders or annotations default to 70% train, 20% validation, and 10% test.
Cloud Streaming
Ask the Agent to connect a camera, select an existing source, and preview a Workflow draft with Cloud Streaming. Use "Network Streams" for a connector on the camera's network, or "Webcam" and "Phone" for a temporary browser session.
To keep an eligible camera preview running, explicitly ask to deploy it. Promotion preserves the current snapshot, runtime state, and sink settings without publishing or restarting. A temporary webcam or phone session cannot be promoted. To apply later edits, explicitly ask to update the deployment; publishing alone does not change the running job.
Name the Workflow or job when asking to stop it. Disconnecting a preview or closing chat does not stop a separate continuous deployment. Follow the Agent quickstart for the full journey, and pricing and limits for billing and lifetime limits. These in-app actions are not standalone public SDK methods.
Background Tasks
Long jobs the Agent starts keep running while you chat: model training, Universe dataset copies, 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.
Workspace LLM Keys
You can run the Agent on your own OpenAI or Azure OpenAI key, so your data does not go through Roboflow's LLM keys. This also covers the Workflow editor assistant, the custom block assistant, and the Agent API.
In your Workspace settings, click "Third Party Keys".
Add your OpenAI API key, or your Azure OpenAI "Resource Name" and "Azure OpenAI API Key".
In "Workspace LLM Keys", pick a "Provider" and "Model". For Azure OpenAI, also enter the "Deployment Name" and "Model Behind This Deployment".
Click "Test Connection".
Turn on "Enforce Workspace LLM Keys", then click "Save".
When this is on, every request uses your key. If your key fails, the request stops with an error and never falls back to Roboflow's keys. Workflow OpenAI and Gemini blocks run on your Workspace keys, and AI features that cannot (ex: other LLM blocks) are turned off. Conversation traces are not recorded, and LLM cost is not charged as credits.
Image generation is turned off while "Enforce Workspace LLM Keys" is on.
Workflow OpenAI blocks and Auto Label use the "OpenAI API Key" under "Third Party Keys". To run them on your Azure OpenAI resource, enter your Azure key there and fill in "Azure OpenAI Endpoint" (ex: https://my-resource.openai.azure.com). In Azure, name each deployment after the model it runs (ex: gpt-6-astra). Without an OpenAI API key, the Agent cannot add OpenAI blocks to your Workflows.
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. A Workflow the agent creates is live right away. An edit publishes right away when the Workflow is set to Auto-publish, and stays a draft until you publish it when the Workflow is Protected.
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.
Send a message to the agent and wait for the whole turn to finish. The reply comes back as one JSON object, not a stream, and a turn that builds or edits Workflows can take minutes. The agent can create new Workflows, edit Workflows linked to the conversation, and answer questions about your workspace. A Workflow it creates is saved and live right away. An edit publishes when the Workflow is set to Auto-publish, and stays a draft when it is Protected. Requires the workflow:create and workflow:update scopes, and the key's user needs the Manage Workflows permission. Each turn spends Roboflow credits, unless the workspace runs the agent on its own LLM key.
Roboflow API key or OAuth access token.
Workspace URL slug.
my-workspaceThe instruction or question for the agent.
Build me a workflow that detects cars and counts themID of a conversation in this workspace to continue. Omit to start a new conversation.
4Fq9ZtLw2XbN7cRkV1sAagent (default) makes changes. In plan mode the agent outlines what it would do without making changes. Any other value means agent.
agentPossible values: The agent's reply.
The agent's response text.
I created a Workflow called Car Counter that detects and counts cars.The conversation ID. Pass it back in later requests to continue the conversation.
4Fq9ZtLw2XbN7cRkV1sAmessage is missing or not a string, or the workspace AI policy refuses the workspace's own LLM key (error_type WORKSPACE_LLM_KEY).
API key missing or invalid.
The workspace's plan has no credits or is not chosen yet (error_type FEATURE_NOT_AVAILABLE), or it is out of credits (error_type CREDIT_LIMIT_REACHED).
Insufficient scopes, the key's user lacks the Manage Workflows permission, the key has no user to act as, agent features are turned off for the workspace (error_type AGENT_DISABLED), conversation_id is not a conversation in this workspace, or the conversation references Workflows outside the key's folder scope.
Workspace usage is paused (error_type USAGE_DISABLED).
Too many requests, or the workspace's own LLM provider key hit its rate limit (error_type WORKSPACE_LLM_KEY).
Internal server error.
The workspace's own LLM provider returned an error (error_type WORKSPACE_LLM_KEY).
The workspace requires its own LLM key, but the key cannot be used (error_type WORKSPACE_LLM_KEY).
POST /{workspace}/agent/chat HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 123
{
"message": "Build me a workflow that detects cars and counts them",
"conversation_id": "4Fq9ZtLw2XbN7cRkV1sA",
"mode": "agent"
}{
"text": "I created a Workflow called Car Counter that detects and counts cars.",
"workflows": [
{
"id": "Qm3RtY8vLp2KsW6nHx0J",
"name": "Car Counter",
"url": "car-counter-1747252800000",
"specification": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"draftSaved": true,
"publication": {
"status": "published",
"protected": true,
"source": "text"
}
}
],
"conversation_id": "4Fq9ZtLw2XbN7cRkV1sA"
}Publish a Workflow
Deploy the latest draft of a Workflow the agent created or edited.
Publish the latest draft version of a Workflow, so the draft the agent saved becomes the version that runs. Requires the workflow:update scope, and the key's user needs the Manage Workflows and Publish Workflows permissions and write access to the Workflow. A project's base Workflow cannot be published here.
Roboflow API key or OAuth access token.
Workspace URL slug.
my-workspaceWorkflow URL slug or Workflow ID.
car-counter-1747252800000The draft was published.
Qm3RtY8vLp2KsW6nHx0Jcar-counter-1747252800000ID of the version that is now published.
8hTq2LmZ0pXc4VnB7wRepublishedPossible values: The Workflow has no unpublished draft.
API key missing or invalid.
Insufficient scopes, agent features turned off for the workspace (error_type AGENT_DISABLED), the Workflow is outside the key's folder scope or the user cannot write to it, the user lacks the Manage Workflows or Publish Workflows permission, the key has no user to act as, or the Workflow is a project's base Workflow.
No Workflow with this URL slug or ID in the workspace.
The draft uses a block that is turned off in this workspace, or another server error.
POST /{workspace}/agent/workflows/{workflowUrl}/publish HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"workflowId": "Qm3RtY8vLp2KsW6nHx0J",
"workflowUrl": "car-counter-1747252800000",
"versionId": "8hTq2LmZ0pXc4VnB7wRe",
"status": "published"
}List Conversations
Return every agent conversation in the workspace, from any member and from both the app and the API, most recently updated first. There is no paging. A folder-scoped key only sees conversations whose Workflows are all in its folders. Requires the workflow:read scope.
Roboflow API key or OAuth access token.
Workspace URL slug.
my-workspaceapi returns conversations started through the Agent API. web returns all others. Any other value is ignored.
Workflow URL slug or ID. Only returns conversations linked to this Workflow.
The workspace's conversations.
API key missing or invalid.
Insufficient scopes, or the workflow filter names a Workflow outside the key's folder scope.
The workflow filter names no Workflow in the workspace.
Internal server error.
GET /{workspace}/agent/conversations HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"conversations": [
{
"id": "4Fq9ZtLw2XbN7cRkV1sA",
"name": "Car Counter",
"type": "workflow",
"source": "api",
"workflowIds": [
"Qm3RtY8vLp2KsW6nHx0J"
],
"created_on": "2026-05-14T20:00:00.000Z",
"updated_on": "2026-05-14T20:05:00.000Z",
"sharing": {
"scope": "private"
}
}
]
}Get a Conversation
Return the full conversation including all messages, oldest first. Requires the workflow:read scope.
Roboflow API key or OAuth access token.
Workspace URL slug.
my-workspaceConversation ID.
4Fq9ZtLw2XbN7cRkV1sAThe conversation with its messages.
4Fq9ZtLw2XbN7cRkV1sAConversation title. Generated after the first reply. Missing until then, unless a linked Workflow's name stands in.
Car CounterConversation kind. workflow once the Agent has created a Workflow in it. Missing on a conversation with no kind yet.
workflowPossible values: Where the conversation started: api for the Agent API, web for the app. Missing on older web conversations.
apiPossible values: IDs of Workflows the conversation created or edited.
["Qm3RtY8vLp2KsW6nHx0J"]2026-05-14T20:00:00.000Z2026-05-14T20:05:00.000ZAPI key missing or invalid.
Insufficient scopes, or the key cannot access the workspace.
No conversation with this ID in the workspace, or it references Workflows outside the key's folder scope.
Internal server error.
GET /{workspace}/agent/conversations/{id} HTTP/1.1
Host: api.roboflow.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"id": "4Fq9ZtLw2XbN7cRkV1sA",
"name": "Car Counter",
"type": "workflow",
"source": "api",
"workflowIds": [
"Qm3RtY8vLp2KsW6nHx0J"
],
"created_on": "2026-05-14T20:00:00.000Z",
"updated_on": "2026-05-14T20:05:00.000Z",
"messages": [
{
"id": "a0c3e1d2-5b7f-4e8a-9c6d-1f2e3a4b5c6d",
"role": "user",
"parts": [
{
"type": "text",
"text": "Build me a workflow that detects cars",
"ANY_ADDITIONAL_PROPERTY": "anything"
}
],
"content": "",
"createdAt": "2026-05-14T20:00:00.000Z",
"status": "text",
"metadata": {
"ANY_ADDITIONAL_PROPERTY": "anything"
}
}
]
}MCP Server
Connect your AI agent to the MCP Server and it can hand work to Roboflow Agent with these tools:
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.
Last updated
Was this helpful?