Agents

Create agent

Changed on Oct 28, 2026

Create a new custom AI agent.

Overview: Agents are specialized AI assistants configured for specific tasks. They can have custom system prompts, access to specific tools, and be limited to certain knowledge bases.

Agent Configuration:

System prompt: Instructions that define agent behavior
Tools: Capabilities like web search, code execution, etc.
Knowledge bases: Data sources the agent can access
Model config: AI model settings (temperature, max tokens)

Use Cases:

Customer support bot with product knowledge
Code review assistant with repository access
HR assistant with policy documents

post/agents/create

Request

Base URL
https://app.pipeshub.com/api/v1
URL
https://app.pipeshub.com/api/v1/agents/create
Auth
- HTTP bearer
- or OAuth 2
  Authorization code: /api/v1/oauth2/authorize
  Client credentials
  Token URL: /api/v1/oauth2/token scopes: agent:write

Request body

namestring required

Agent display name. Surrounding whitespace is trimmed; a blank name is refused with 400 (VALIDATION_ERROR, "Name is required").

descriptionstring

What the agent does

startMessagestring

Initial greeting shown when conversation starts

systemPromptstring

System instructions for the agent

instructionsstring

Additional agent execution instructions

tagsstring[]

shareWithOrgboolean

Share agent with the organization

isServiceAccountboolean

Create the agent as a service-account agent

serviceAccountUserIdstring

The userId of the service account this agent should search knowledge as, as returned by the service accounts API. Only valid on a service-account agent: sending it without isServiceAccount is refused rather than ignored, so a request cannot quietly create an agent that searches as its creator. Omit it and the agent searches as its creator. Whitespace around it is removed first; 1-128 characters.

defaultReasoningEffort'none' | 'low' | 'medium' | 'high' | 'max' nullable

Agent-level reasoning effort used when a chat request omits its own.

apiToolsetToolsstring[]

API toolset operations the agent may call, each <toolsetId>:<operation> (see /api-toolsets). A service-account agent may only use toolsets with a shared credential.

sendUserContextboolean

When true (default), include the current user's name, email, and organization in this agent's system prompt. When false, omit that profile data.

Example request

{
  "name": "Product Support Agent"
}

Response

Agent created

status'success' | 'partial_success' required

messagestring required

Changes

Oct 28, 2026dbb5e203b445 Revision changes
- breaking
  added to the // request property allOf list
- breaking
  removed subschema #1 subschema #2 from the request property anyOf list
- breaking
  removed the enum value calendar of the request property //
- breaking
  removed the enum value clickup of the request property //
- breaking
  removed the enum value confluence of the request property //
- breaking
  removed the enum value confluencedatacenter of the request property //
- breaking
  removed the enum value docs of the request property //
- breaking
  removed the enum value drive of the request property //
- breaking
  removed the enum value github of the request property //
- breaking
  removed the enum value gmail of the request property //
- breaking
  removed the enum value jira of the request property //
- breaking
  removed the enum value jiradatacenter of the request property //
- breaking
  removed the enum value lumos of the request property //
- breaking
  removed the enum value mariadb of the request property //
- breaking
  removed the enum value onedrive of the request property //
- breaking
  removed the enum value outlook of the request property //
- breaking
  removed the enum value redshift of the request property //
- breaking
  removed the enum value salesforce of the request property //
- breaking
  removed the enum value sharepoint of the request property //
- breaking
  removed the enum value sheets of the request property //
- breaking
  removed the enum value slack of the request property //
- breaking
  removed the enum value teams of the request property //
- breaking
  removed the enum value zoom of the request property //
- breaking
  the // request property's minLength was increased from 0 to 1
- breaking
  the request property's minLength was increased from 0 to 1
- breaking
  the //// request property's minLength was increased from 0 to 1
- breaking
  the //// request property's minLength was increased from 0 to 1
- breaking
  removed subschema #1 subschema #2 from the / request property oneOf list
- breaking
  added the pattern \S to the request property //
- breaking
  added the pattern \S to the request property
- breaking
  added the pattern \S to the request property ////
- breaking
  added the pattern \S to the request property ////
- breaking
  the // request property type changed from string to no type
- warning
  the request property's maxLength was set to 128
- info
  added the new optional request property
- info
  added subschema #1 subschema #2 to the request property anyOf list
- info
  added subschema #1 subschema #2 to the / request property oneOf list
- info
  added the media type application/json for the response with the status
- info
  added the media type application/json for the response with the status
- info
  added the non-success response with the status
- info
  added the non-success response with the status
Oct 26, 2026fc76aa045994 Revision changes
- warning
  added the new docs enum value to the /// response property for the response status
- warning
  added the new sheets enum value to the /// response property for the response status
- info
  added the new optional request property
- info
  added the new optional request property
- info
  added the new docs enum value to the request property //
- info
  added the new sheets enum value to the request property //
- info
  added the optional property / to the response with the status
- info
  added the optional property / to the response with the status

Operation history (7 revisions)