Build overview

An agent is assembled from parts: a playbook and the tools it can call, a function with its branches and variables, an API tool, an MCP server, the project’s variables, and the documents its knowledge base retrieves from. All of them can be created and changed from outside the Studio, which is what makes generating agents from a template, importing them from another system, or keeping a set of projects consistent with each other possible.

Endpoints

Agent

Endpoint	Description
GET Get agent	Get agent configuration.
PATCH Update agent	Update agent configuration.

Playbook

Endpoint	Description
GET List playbooks	List all playbooks by project ID.
POST Create playbook	Create a new playbook.
POST Create many playbooks	Create multiple new playbooks.
GET Get playbook	Get a playbook by ID.
PATCH Update playbook	Update a playbook by ID.
DELETE Delete playbook	Delete a playbook by ID.

Function

Endpoint	Description
GET List functions	List all functions by project ID.
POST Create function	Create a new function.
POST Create many functions	Create multiple new functions.
GET Get function	Get a function by ID.
PATCH Update function	Update a function by ID.
DELETE Delete function	Delete a function by ID.

Function path

Endpoint	Description
GET List paths	List all paths by function ID.
POST Create path	Create a new path.
POST Create many paths	Create multiple new paths.
GET Get path	Get a path by ID.
PATCH Update path	Update a path by ID.
DELETE Delete path	Delete a path by ID.

Function variable

Endpoint	Description
GET List variables	List all variables by function ID.
POST Create variable	Create a new variable.
POST Create many variables	Create multiple new variables.
GET Get variable	Get a variable by ID.
PATCH Update variable	Update a variable by ID.
DELETE Delete variable	Delete a variable by ID.

Tool

Endpoint	Description
GET List tools	List all tools for the agent or a specific playbook.
POST Create tool	Create a new tool.
POST Create many tools	Create multiple new tools.
GET Get tool	Get a tool by ID.
PATCH Update tool	Update a tool by ID.
DELETE Delete tool	Delete a tool by ID.

API tool

Endpoint	Description
GET List API tools	List all API tools by project ID.
POST Create API tool	Create a new API tool.
POST Create many API tools	Create multiple new API tools.
GET Get API tool	Get an API tool by ID.
PATCH Update API tool	Update an API tool by ID.
DELETE Delete API tool	Delete an API tool by ID.

API tool variable

Endpoint	Description
GET List variables	List all variables by API tool ID.
POST Create variable	Create a new variable.
POST Create many variables	Create multiple new variables.
GET Get variable	Get an variable by ID.
PATCH Update variable	Update an variable by ID.
DELETE Delete variable	Delete an variable by ID.

Variable

Endpoint	Description
GET List variables	List all variables by project ID.
POST Create variable	Create a new variable.
POST Create many variables	Create multiple new variables.
GET Get variable	Get a variable by ID.
PATCH Update variable	Update a variable by ID.
DELETE Delete variable	Delete a variable by ID.

MCP server

Endpoint	Description
GET List MCP servers	List all MCP servers by project ID.
POST Create MCP server	Create a new MCP server.
GET Get MCP server	Get an MCP server by ID.
PATCH Update MCP server	Update an MCP server by ID.
DELETE Delete MCP server	Delete an MCP server by ID.
PUT Sync MCP server	Sync tool changes for an MCP server by ID.

MCP tool

Endpoint	Description
GET List MCP tools	List all MCP tools by project ID.
GET Get MCP tool	Get an MCP tool by ID.

Knowledge base document

Endpoint	Description
GET List documents	List all documents by project ID.
POST Create URL document	Create a new document from a URL.
POST Create text document	Create a new document from raw text.
POST Create table document	Create a new document from structured data.
GET Get document	Get a document by ID.
PATCH Update document	Update a document by ID.
DELETE Delete document	Delete a document by ID.

How the build endpoints are shaped

Every resource follows the same six-verb pattern, so learning one teaches the rest:

Verb	Path	Purpose
`GET`	`/{resource}`	list everything in the project
`POST`	`/{resource}`	create one
`POST`	`/{resource}/batch`	create many in a single call
`GET`	`/{resource}/{id}`	fetch one
`PATCH`	`/{resource}/{id}`	change part of one
`DELETE`	`/{resource}/{id}`	remove one

The batch variant matters when you are importing. Creating fifty variables one call at a time is fifty round trips and fifty chances to end up half migrated; one batch call is atomic from your side.

Scoping every call

Build endpoints act inside one environment of one project, so both are required query parameters:

curl "https://realtime-api.voiceflow.com/v1/stable/function?projectID=$VF_PROJECT_ID&environmentAlias=main" \
  -H "Authorization: Bearer $VF_PAT"

Editing main changes what your team sees in the Creator. To stage changes without touching it, clone an environment first, build against the clone, and merge when you are satisfied.

How the pieces relate

A playbook is the unit of agent behaviour. It holds instructions and the tools it may call.
Tools are what a playbook can do. An API tool calls an HTTP endpoint; a function runs your own code; an MCP server contributes a set of MCP tools discovered from that server.
Function paths are the branches a function can exit through, and function variables are its inputs and outputs. Both belong to a function and are managed separately, so you can add a branch without rewriting the function.
Variables are project state that persists across a conversation.
Knowledge base documents are the corpus the agent retrieves from. Create them from a URL, from text, or by uploading a table.

Where to go next

Once an agent is built, publish it to make the changes live, and run a conversation against it to see how it behaves.

Getting started

Running agents

Build

Manage

Publishing

Observe

Insights

QA

Analytics

Webhooks

Endpoints

Agent

Playbook

Function

Function path

Function variable

Tool

API tool

API tool variable

Variable

MCP server

MCP tool

Knowledge base document

How the build endpoints are shaped

Scoping every call

How the pieces relate

Where to go next

​Endpoints

​Agent

​Playbook

​Function

​Function path

​Function variable

​Tool

​API tool

​API tool variable

​Variable

​MCP server

​MCP tool

​Knowledge base document

​How the build endpoints are shaped

​Scoping every call

​How the pieces relate

​Where to go next

Endpoints

Agent

Playbook

Function

Function path

Function variable

Tool

API tool

API tool variable

Variable

MCP server

MCP tool

Knowledge base document

How the build endpoints are shaped

Scoping every call

How the pieces relate

Where to go next