Skip to main content
POST
/
agent-setup
Process agent setup steps
curl --request POST \
  --url https://api.beamstudio.ai/agent-setup \
  --header 'Content-Type: application/json' \
  --header 'current-workspace-id: <current-workspace-id>' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "agentId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "agentSetupStep": "GENERATE_SOP",
  "query": "I want to create an agent that helps users with customer support inquiries",
  "contextFileIds": [
    "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "b2c3d4e5-f6a7-8901-bcde-f12345678901"
  ]
}
'
{
  "nextStep": "SOP_GENERATION",
  "agentResponse": {
    "agent": {
      "name": "Customer Support Agent",
      "creatorId": "123e4567-e89b-12d3-a456-426614174001",
      "type": "beam-os",
      "vectorDbId": "123e4567-e89b-12d3-a456-426614174002",
      "category": {
        "title": "Customer Support",
        "publish": true,
        "id": "<string>",
        "createdAt": "2023-11-07T05:31:56Z",
        "updatedAt": "2023-11-07T05:31:56Z",
        "deletedAt": "2023-11-07T05:31:56Z"
      },
      "id": "<string>",
      "createdAt": "2023-11-07T05:31:56Z",
      "updatedAt": "2023-11-07T05:31:56Z",
      "description": "This agent handles customer inquiries, support tickets, and provides automated responses",
      "workspaceId": "123e4567-e89b-12d3-a456-426614174000",
      "defaultTaskId": "task_template_001",
      "themeIconUrl": "https://example.com/icons/agent-icon.png",
      "agentCategoryId": "cat_customer_service",
      "userAccessTokenId": "123e4567-e89b-12d3-a456-426614174003",
      "agentSetupSessionId": "123e4567-e89b-12d3-a456-426614174004",
      "agentIntroMessage": "Hello! I'm your customer support assistant. How can I help you today?",
      "agentSetupMessage": "Let's configure your agent to handle customer support tasks",
      "skipAgentSetupSop": true,
      "deletedAt": "2023-11-07T05:31:56Z"
    },
    "contextFiles": [
      {
        "name": "product_catalog.pdf",
        "userId": "string",
        "uploadStatus": "processing",
        "uploadSource": "file_upload",
        "isForAgentDatabase": true,
        "agentId": "string",
        "mimeType": "application/pdf",
        "id": "<string>",
        "createdAt": "2023-11-07T05:31:56Z",
        "updatedAt": "2023-11-07T05:31:56Z",
        "src": "string",
        "fileKey": "string",
        "taskId": "string",
        "agentTaskId": "string",
        "url": "string",
        "datasourceConnectionId": "string",
        "externalFileId": "string",
        "deletedAt": "2023-11-07T05:31:56Z"
      }
    ]
  }
}

Authorizations

​
x-api-key
string
header
required

Headers

​
current-workspace-id
string
required

Body

application/json
​
agentId
string<uuid>
required

UUID of the agent. Required for all setup steps (GENERATE_SOP and onwards) to identify which agent is being configured.

Example:

"f47ac10b-58cc-4372-a567-0e02b2c3d479"

​
agentSetupStep
enum<string>
required

Current step in the agent setup workflow. Use /agent-context and /agent-creation first, then use this endpoint for the remaining steps:

• GENERATE_SOP - Generate Standard Operating Procedures for the agent (requires query) • GRAPH_GENERATION - Create the agent's workflow graph • TOOL_MATCHING - Match existing tools to the agent's needs • TOOL_GENERATION - Generate new custom tools if needed • TOOL_INTEGRATION - Integrate selected tools with the agent • UPDATE_AGENT - Finalize and update the agent configuration • AGENT_UPDATED - Confirmation that setup is complete

Available options:
GENERATE_SOP,
GRAPH_GENERATION,
TOOL_MATCHING,
TOOL_GENERATION,
TOOL_INTEGRATION,
UPDATE_AGENT,
AGENT_UPDATED,
CREATE_TASK
Example:

"GENERATE_SOP"

​
query
string

User input or instructions for the current setup step. Use this to provide context about what the agent should do, describe its purpose, or give feedback during the setup process.

Example:

"I want to create an agent that helps users with customer support inquiries"

​
contextFileIds
string<uuid>[]

Array of context file UUIDs to attach to the agent. These files provide additional knowledge or reference materials that the agent can use when processing requests.

Example:
[
  "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "b2c3d4e5-f6a7-8901-bcde-f12345678901"
]

Response

Agent setup step processed successfully. Response structure varies by step (see operation description).

​
nextStep
enum<string>
required

The next step in the agent setup workflow. Use this value to determine which step to call next.

Available options:
GENERATE_SOP,
GRAPH_GENERATION,
TOOL_MATCHING,
TOOL_GENERATION,
TOOL_INTEGRATION,
UPDATE_AGENT,
AGENT_UPDATED,
CREATE_TASK
Example:

"SOP_GENERATION"

​
agentResponse
object
required

Agent creation response containing the created agent details and associated context files.