The Agent object

An Agent represents a single prompt chain with an option to trigger system events. Agents do not hold memory of previous interactions, intead is functionally equivalent to a workflow. It is a single pass operation.

class Agent {
    id            String
    name          String
    description   String

    variables     Dictionary<String, String>
    fields        Field[]
    workflow      Node[]
}

To understand the agent object further, with detailed explainations see What are agents

List all Agents

Retrieves a list of agents

GET /api/v1/agent

response:

200 {
    [
        {
           id: "movie-agent",
            name: "Movie Script agent",
            description: "An Agent that generates a movie script",
            variables: {
                "field1": "Value1",
                "field2": "value2",
                ...
            },
            fields: [],
            workflow: [
                {
                    "type": "prompt",
                    "name": "Sypnosis",

                    "system": "You are a story development expert creating a synopsis for a {genre} film according to the user's request",
                    "user": "{prompt}",
                    "apikey": "{replicateAPI}",
                    "llm": "replicate",
                    "model": "google-deepmind/gemma-3-27b-it",
                    "temperature": 1,
                    "maxTokens": 2000,
                    "output": "context",
                },
                {
                    "type": "prompt",
                    "name": "character dev",

                    "system": "You are a character development specialist for {genre} films. Given the film's sypnosis enclosed in ### and the user's main request, \n Write the film's character development plans",
                    "user": "### {context} ### {prompt}",
                    "apikey": "{replicateAPI}",
                    "llm": "replicate",
                    "model": "google-deepmind/gemma-3-27b-it",
                    "temperature": 1,
                    "maxTokens": 2000,
                    "output": "context",
                },
                {
                    "name": "Return",
                    "type": "return",
                    "output": "context"
                }
            ] 
        },
        ...
    ]
}

Search Agents

Its also possible to filter and query agents, via query parameter. This is a fuzzy query search

GET /api/v1/agent?query=movie%20script

This returns a list of all agents, limit by 5, where the agent's description contains your query string.

Create a new Agent

Creates a new Agent.

POST /api/v1/agent

header {
    "Content-Type": "application/json",
    "apikey": "apikey123"
}

body {
    id: "movie-agent",
    name: "Movie Script agent",
    description: "An Agent that generates a movie script",
    variables: {
        "field1": "Value1",
        "field2": "value2",
        ...
    },
    fields: [],
    workflow: [
        {
            "type": "prompt",
            "name": "Sypnosis",

            "system": "You are a story development expert creating a synopsis for a {genre} film according to the user's request",
            "user": "{prompt}",
            "apikey": "{replicateAPI}",
            "llm": "replicate",
            "model": "google-deepmind/gemma-3-27b-it",
            "temperature": 1,
            "maxTokens": 2000,
            "output": "context",
        },
        {
            "type": "prompt",
            "name": "character dev",

            "system": "You are a character development specialist for {genre} films. Given the film's sypnosis enclosed in ### and the user's main request, \n Write the film's character development plans",
            "user": "### {context} ### {prompt}",
            "apikey": "{replicateAPI}",
            "llm": "replicate",
            "model": "google-deepmind/gemma-3-27b-it",
            "temperature": 1,
            "maxTokens": 2000,
            "output": "context",
        },
        {
            "name": "Return",
            "type": "return",
            "output": "context"
        }
    ]
}

id (String, required)
Unique Identifier for the agent. This is what is used to reference an agent when a workflow is called.

name (String, required)
Identifier for the agent. This is the printable name of the agent

workflow (Array of Node, required)
Represents the main workflow prompt chain node. Where each node is a subclass to the Base Node. Refer to Data Model for description of the Node fields

variables (dict of String key, String value | defaults to empty obj)
Represents the key value pair of variables that will be substituded within the workflow (promptChain in backend).

fields (Array of Field | defaults to empty Array)
The component schema used to define the input body that this agent expects for execution. This is used by a separate Client React SDK that is used to render a dynamic UI for making agent requests.

Responses

201 Agent has been created successfully

{
    id: "movie-agent",
    name: "Movie Script agent",
    description: "An Agent that generates a movie script",
    variables: {
        "field1": "Value1",
        "field2": "value2",
        ...
    },
    fields: [],
    workflow: [
        {
            "type": "prompt",
            "name": "Sypnosis",

            "system": "You are a story development expert creating a synopsis for a {genre} film according to the user's request",
            "user": "{prompt}",
            "apikey": "{replicateAPI}",
            "llm": "replicate",
            "model": "google-deepmind/gemma-3-27b-it",
            "temperature": 1,
            "maxTokens": 2000,
            "output": "context",
        },
        {
            "type": "prompt",
            "name": "character dev",

            "system": "You are a character development specialist for {genre} films. Given the film's sypnosis enclosed in ### and the user's main request, \n Write the film's character development plans",
            "user": "### {context} ### {prompt}",
            "apikey": "{replicateAPI}",
            "llm": "replicate",
            "model": "google-deepmind/gemma-3-27b-it",
            "temperature": 1,
            "maxTokens": 2000,
            "output": "context",
        },
        {
            "name": "Return",
            "type": "return",
            "output": "context"
        }
    ] 
}

400 Unauthorized

Create many Agents in a batch

Creates multiple agents in a single API call. In this instance, the Body must be an array of Agent Objects

POST /api/v1/agent

header {
    "Content-Type": "application/json",
    "apikey": "apikey123"
}

body {
    [
        {
            id: "movie-agent",
            name: "Movie Script agent",
            description: "An Agent that generates a movie script",
            variables: {
                "field1": "Value1",
                "field2": "value2",
                ...
            },
            fields: [],
            workflow: [
                {
                    "type": "prompt",
                    "name": "Sypnosis",

                    "system": "You are a story development expert creating a synopsis for a {genre} film according to the user's request",
                    "user": "{prompt}",
                    "apikey": "{replicateAPI}",
                    "llm": "replicate",
                    "model": "google-deepmind/gemma-3-27b-it",
                    "temperature": 1,
                    "maxTokens": 2000,
                    "output": "context",
                },
                {
                    "type": "prompt",
                    "name": "character dev",

                    "system": "You are a character development specialist for {genre} films. Given the film's sypnosis enclosed in ### and the user's main request, \n Write the film's character development plans",
                    "user": "### {context} ### {prompt}",
                    "apikey": "{replicateAPI}",
                    "llm": "replicate",
                    "model": "google-deepmind/gemma-3-27b-it",
                    "temperature": 1,
                    "maxTokens": 2000,
                    "output": "context",
                },
                {
                    "name": "Return",
                    "type": "return",
                    "output": "context"
                }
            ]
        },
        ...
    ]
}

id (String, required)
Unique Identifier for the agent. This is what is used to reference an agent when a workflow is called.

name (String, required)
Identifier for the agent. This is the printable name of the agent

workflow (Array of Node, required)
Represents the main workflow prompt chain node. Where each node is a subclass to the Base Node. Refer to Data Model for description of the Node fields

variables (dict of String key, String value | defaults to empty obj)
Represents the key value pair of variables that will be substituded within the workflow (promptChain in backend).

fields (Array of Field | defaults to empty Array)
The component schema used to define the input body that this agent expects for execution. This is used by a separate Client React SDK that is used to render a dynamic UI for making agent requests.

Responses

201 Agent has been created successfully

[
{
    id: "movie-agent",
    name: "Movie Script agent",
    description: "An Agent that generates a movie script",
    variables: {
        "field1": "Value1",
        "field2": "value2",
        ...
    },
    fields: [],
    workflow: [
        {
            "type": "prompt",
            "name": "Sypnosis",

            "system": "You are a story development expert creating a synopsis for a {genre} film according to the user's request",
            "user": "{prompt}",
            "apikey": "{replicateAPI}",
            "llm": "replicate",
            "model": "google-deepmind/gemma-3-27b-it",
            "temperature": 1,
            "maxTokens": 2000,
            "output": "context",
        },
        {
            "type": "prompt",
            "name": "character dev",

            "system": "You are a character development specialist for {genre} films. Given the film's sypnosis enclosed in ### and the user's main request, \n Write the film's character development plans",
            "user": "### {context} ### {prompt}",
            "apikey": "{replicateAPI}",
            "llm": "replicate",
            "model": "google-deepmind/gemma-3-27b-it",
            "temperature": 1,
            "maxTokens": 2000,
            "output": "context",
        },
        {
            "name": "Return",
            "type": "return",
            "output": "context"
        }
    ] 
},
...
]

400 Unauthorized

Retrieve an Agent

Retrieves specific details about one agent:

GET /api/v1/agent/{agentId}

header {
    apikey: "apikey123"
}

Responses

200 Agent details retrieved successfully

{
    id: "movie-agent",
    name: "Movie Script agent",
    description: "An Agent that generates a movie script",
    variables: {
        "field1": "Value1",
        "field2": "value2",
        ...
    },
    fields: [],
    workflow: [
        {
            "type": "prompt",
            "name": "Sypnosis",

            "system": "You are a story development expert creating a synopsis for a {genre} film according to the user's request",
            "user": "{prompt}",
            "apikey": "{replicateAPI}",
            "llm": "replicate",
            "model": "google-deepmind/gemma-3-27b-it",
            "temperature": 1,
            "maxTokens": 2000,
            "output": "context",
        },
        {
            "type": "prompt",
            "name": "character dev",

            "system": "You are a character development specialist for {genre} films. Given the film's sypnosis enclosed in ### and the user's main request, \n Write the film's character development plans",
            "user": "### {context} ### {prompt}",
            "apikey": "{replicateAPI}",
            "llm": "replicate",
            "model": "google-deepmind/gemma-3-27b-it",
            "temperature": 1,
            "maxTokens": 2000,
            "output": "context",
        },
        {
            "name": "Return",
            "type": "return",
            "output": "context"
        }
    ] 
}

Update an Agent

Updates the current agent. Updates are rewrites, thus, the frontend needs to send the full revision JSON for the agent

POST /api/v1/agent/{agentId}

header {
    "Content-Type": "application/json",
    "apikey": "apikey123"
}

body {
    id: "movie-agent",
    name: "Movie Script agent",
    description: "An Agent that generates a movie script",
    variables: {
        "field1": "Value1",
        "field2": "value2",
        ...
    },
    fields: [],
    workflow: [
        {
            "type": "prompt",
            "name": "Sypnosis",

            "system": "You are a story development expert creating a synopsis for a {genre} film according to the user's request",
            "user": "{prompt}",
            "apikey": "{replicateAPI}",
            "llm": "replicate",
            "model": "google-deepmind/gemma-3-27b-it",
            "temperature": 1,
            "maxTokens": 2000,
            "output": "context",
        },
        {
            "type": "prompt",
            "name": "character dev",

            "system": "You are a character development specialist for {genre} films. Given the film's sypnosis enclosed in ### and the user's main request, \n Write the film's character development plans",
            "user": "### {context} ### {prompt}",
            "apikey": "{replicateAPI}",
            "llm": "replicate",
            "model": "google-deepmind/gemma-3-27b-it",
            "temperature": 1,
            "maxTokens": 2000,
            "output": "context",
        },
        {
            "name": "Return",
            "type": "return",
            "output": "context"
        }
    ]
}

id (String, required)
Unique Identifier for the agent. This is what is used to reference an agent when a workflow is called.MUST BE UNIQUE

name (String, required)
Identifier for the agent. This is the printable name of the agent. MUST BE UNIQUE

description (String)
descriptions for the agent.

workflow (Array of Node, required)
Represents the main workflow prompt chain node. Where each node is a subclass to the Base Node. Refer to Data Model for description of the Node fields

variables (dict of String key, String value | defaults to empty array)
Represents the key value pair of variables that will be substituded within the workflow (promptChain in backend).

fields (Array of Field)
The component schema used to define the input body that this agent expects for execution. This is used by a separate Client React SDK that is used to render a dynamic UI for making agent requests.

Response

201 agent updated successfully

{
    id: "movie-agent",
    name: "Movie Script agent",
    description: "An Agent that generates a movie script",
    variables: {
        "field1": "Value1",
        "field2": "value2",
        ...
    },
    fields: [],
    workflow: [
        {
            "type": "prompt",
            "name": "Sypnosis",

            "system": "You are a story development expert creating a synopsis for a {genre} film according to the user's request",
            "user": "{prompt}",
            "apikey": "{replicateAPI}",
            "llm": "replicate",
            "model": "google-deepmind/gemma-3-27b-it",
            "temperature": 1,
            "maxTokens": 2000,
            "output": "context",
        },
        {
            "type": "prompt",
            "name": "character dev",

            "system": "You are a character development specialist for {genre} films. Given the film's sypnosis enclosed in ### and the user's main request, \n Write the film's character development plans",
            "user": "### {context} ### {prompt}",
            "apikey": "{replicateAPI}",
            "llm": "replicate",
            "model": "google-deepmind/gemma-3-27b-it",
            "temperature": 1,
            "maxTokens": 2000,
            "output": "context",
        },
        {
            "name": "Return",
            "type": "return",
            "output": "context"
        }
    ]
}

Delete an Agent

Deletes an Agent from the Database

DELETE /api/v1/agent/{agentId}

header {
    apikey: apikey123
}

Response

200 Agent deleted successfully