Agent Management

In Caddie, a user's chat experience is delivered through agents. Agents allow you to deliver a highly customized chat experience to a specific subset of users within an organization. An agent is a distinct chat environment, including the following customizeable fields:

• branding, styling, and themes
• system prompt/generic admin-level language model prompting
• data access restrictions

Agents are underneath Organizations in the permissions and access control hierarchy, so they inherit their organization's controls. This means that an agent can only belong to a single organization, and that an agent underneath Organization A can never access data or documents in Organization B.

Create an agent

Give the agent a name and description, and specify which model to use.

fetch("http://localhost:3000/api/agent", {
	method: "POST",
	headers: {
		"Content-Type": 'application/json',
		"X-API-KEY": '',
		"X-Organization-Id": ''
	},
	body: JSON.stringify({
		"name": "",
		"description": "",
		"modelId": "anthropic.claude-sonnet-4-20250514-v1:0"
	})
})

Required fields:

• name: string, minimum 2 characters, maximum 50 characters
• description: string, minimum 10 characters, maximum 500 characters
• modelId: the following models are supported in Caddie, but support may vary in AWS Bedrock based on region. For more details, see AWS documentation: https://docs.aws.amazon.com/bedrock/latest/userguide/models-supported.html
  • Claude Sonnet 4: anthropic.claude-sonnet-4-20250514-v1:0
  • Claude Sonnet 3.7: anthropic.claude-3-7-sonnet-20250219-v1:0
  • Claude Haiku 3.5: anthropic.claude-3-5-haiku-20241022-v1:0
  • Nova Pro: amazon.nova-pro-v1:0
  • Nova Lite: amazon.nova-lite-v1:0

In addition to the required fields, you can further customize the agent on creation, or using the update endpoint. For a full list of these customization options/fields, see the section for updating an agent.

Get agent metadata

To get all the config data of a particular agent, use the /api/agent/example-agent-id endpoint:

fetch("http://localhost:3000/api/agent/example-agent-id", {
	method: "GET",
	headers: {
		"X-API-KEY": '',
		"X-Organization-Id": "org the agent belongs to"
	}
})

List agents by organization ID

To view all the agents within a particular organization, provide the organization ID as a query parameter to /api/agent to get a list of agents within an organization.

Request:

fetch("http://localhost:3000/api/agent?organizationId=example-org-id", {
	method: "GET",
	headers: {
		"X-API-KEY": '',
		"X-Organization-Id": ''
	}
})

Update an agent

Pass the id of agent you want to modify. The body of the request must conform to the field schema below.

fetch("http://localhost:3000/api/agent/id-of-agent", {
	method: "PATCH",
	headers: {
		"Content-Type": 'application/json',
		"X-API-KEY": '',
		"X-Organization-Id": ''
	},
	body: {} // body must conform to schema below
})

Field schema for agent updates. All fields are optional. If optional fields are not passed, the agent will keep its previous settings values.

• name: string,
• description: string
• modelId: string, must be a valid AI model in AWS (full list with model ID values here)
• isActive: boolean
• instructions: string value. This is the system prompt, and is very important for getting good responses from the Agent. Modify with care.
• temperature: number, floating point value that controls randomness/strictness of model's output. For more detail, see the AWS documentation
• isToolKnowledgebaseEnabled: boolean
• isCustomMetadataFilteringEnabled: boolean
• toolKnowledgebaseSettings: JSON object string, contains:
  • maxResults: integer
  • minSimilarityScore: number, floating point value
• isToolCreateDocumentEnabled: boolean
• isToolUpdateDocumentEnabled: boolean
• theme: enum(['light', 'dark']), controls whether the Agent UI is light or dark mode

Grant agent access to document folder

To grant an agent access to certain documents within an organization, place the documents in a folder(s). Then, grant the agent access to that folder. Access is granted hierarchically, so granting access to a folder will also grant access to all subfolders.

Provide an array of folder ids (UUID strings). Folders must belong to the organization in headers, X-Organization-ID. The list provided in this request will overwrite the existing list, so, to provide a new list of documents

fetch("http://localhost:3000/api/agent/id-of-agent/folder", {
	method: "POST",
	headers: {
		"Content-Type": 'application/json',
		"X-API-KEY": '',
		"X-ORGANIZATION-ID": ''
	},
	body: {
		"folderIds": [] //array of folder UUIDs
	}
})

Delete an agent

Pass the id of the agent in the url:

fetch("http://localhost:3000/api/agent/id-of-agent", {
	method: "DELETE",
	headers: {
		"Content-Type": 'application/json',
		"X-API-KEY": '',
		"X-Organization-Id": ''
	}
})