Skip to content
Intellia Overview
API Reference
API Resources
Agents

Agents

Manage AI agents and their configurations.

Agent Management

List Agents 

GET /orgs/{organizationId}/agents

Query Parameters:

  • limit (optional): Number of results (default: 20)
  • cursor (optional): Pagination offset
  • orderBy (optional): Field to sort by
  • all (optional): Set to "true" to list all agents (requires Admin/Owner role)
  • q (optional): Search string to filter agents by name
By default, this endpoint returns only agents the user has permission to access. Admins and Owners can use all=true to list all agents in the organization.

Response:

{
  "items": [
    {
      "id": "agent-123",
      "organizationId": "org-456",
      "name": "Customer Support Agent",
      "description": "Handles customer inquiries",
      "instructions": "You are a helpful...",
      "model": "gpt5.2",
      "creativityScore": "0.4",
      "createdAt": "2024-01-01T00:00:00Z",
      "updatedAt": "2024-01-01T00:00:00Z"
    }
  ],
  "totalRows": 1,
  "offset": 0
}

Create Agent 

POST /orgs/{organizationId}/agents

Required Fields:

  • name: Agent name
  • description: Agent description
  • instructions: System instructions for the agent
  • model: AI model to use (e.g., “gpt5.2”, “gemini”)

Optional Fields:

  • creativityScore: String value between “0” and “1” (default: “0.4”)
  • reasoning: Reasoning effort — one of "none", "low", "medium", "high"
  • emailAddress: Email address for email-based interactions
  • emailFilters: Filters for incoming emails
  • emailAttachmentsToKnowledgeBaseId: KB ID to store email attachments

Request Body:

{
  "name": "Customer Support Agent",
  "description": "Handles customer inquiries",
  "instructions": "You are a helpful customer support agent...",
  "model": "gpt5.2",
  "creativityScore": "0.4"
}

Response: Returns created agent with id field

Get Agent 

GET /orgs/{organizationId}/agents/{id}

Returns a single agent’s details. The {id} parameter can be:

  • A regular agent ID
  • A default agent ID (system will create if not exists)

Update Agent 

PUT /orgs/{organizationId}/agents/{id}

Required Fields: All fields from create (name, description, instructions, model)

Request Body:

{
  "name": "Updated Agent Name",
  "description": "Updated description",
  "instructions": "Updated instructions...",
  "model": "gpt5.2",
  "creativityScore": "0.6",
  "emailAddress": "agent@example.com"
}

Delete Agent 

DELETE /orgs/{organizationId}/agents/{id}

Permanently deletes the agent and all its knowledge base attachments.

Response:

{
  "organizationId": "org-123",
  "agentId": "agent-456"
}

Update Agent Visibility 

PUT /orgs/{organizationId}/agents/{id}/visibility

Flip an agent between public and private. Requires an Admin/Owner role, and publishing (public) is only permitted on orgs configured to host public content.

Request Body:

{
  "visibility": "public"
}

Response:

{
  "organizationId": "org-123",
  "agentId": "agent-456",
  "visibility": "public"
}

Agent Attachments

Agents can be enhanced with knowledge bases, tools, other agents, and action chains.

Knowledge Base Attachments

List Knowledge Bases 

GET /orgs/{organizationId}/agents/{id}/knowledgebases

Response:

{
  "organizationId": "org-123",
  "agentId": "agent-456",
  "knowledgebases": [
    {
      "organizationId": "org-123",
      "agentId": "agent-456",
      "knowledgeBaseId": "kb-789",
      "kbOrganizationId": "org-123",
      "kbTitle": "Product Documentation",
      "creatorUserId": "user-123",
      "createdAt": "2024-01-01T00:00:00Z"
    }
  ]
}

Attach Knowledge Base 

POST /orgs/{organizationId}/agents/{id}/knowledgebases

Request Body:

{
  "knowledgeBaseId": "kb-123",
  "kbOrganizationId": "org-123"
}

Optional: kbOrganizationId - If attaching a knowledge base from a different organization. The knowledge base must be public and owned by an organization that hosts public content; a public knowledge base owned by an ordinary organization is not attachable across organizations. If supplied, the value must match the knowledge base’s actual owner, or the request is rejected.

Detach Knowledge Base 

DELETE /orgs/{organizationId}/agents/{id}/knowledgebases/{knowledgeBaseId}

Tool Attachments

Tools extend agent capabilities with external integrations.

List Agent’s Tools 

GET /orgs/{organizationId}/agents/{id}/tools

Returns array of AgentToolAttachment objects with toolCode and configuration.

Attach Tool 

POST /orgs/{organizationId}/agents/{id}/tools

Request Body:

{
  "toolCode": "web_search",
  "configuration": {
    "searchEngine": "google"
  }
}
The field is configuration (not config). Tool configuration structure depends on the specific tool.

Update Tool Configuration 

PUT /orgs/{organizationId}/agents/{id}/tools/{toolCode}

Request Body:

{
  "toolCode": "web_search",
  "configuration": {
    "searchEngine": "bing"
  }
}

Detach Tool 

DELETE /orgs/{organizationId}/agents/{id}/tools/{toolCode}

Agent-to-Agent Attachments

Allow agents to collaborate by attaching other agents as sub-agents.

List Agent Attachments 

GET /orgs/{organizationId}/agents/{id}/agent-attachments

Returns array of AgentToAgentAttachmentView objects.

Attach Agent 

POST /orgs/{organizationId}/agents/{id}/agent-attachments

Request Body:

{
  "targetAgentId": "agent-456",
  "instructions": "Use this agent for technical questions"
}

Update Agent Attachment 

PUT /orgs/{organizationId}/agents/{id}/agent-attachments/{targetAgentId}

Request Body:

{
  "instructions": "Updated routing instructions"
}

Detach Agent 

DELETE /orgs/{organizationId}/agents/{id}/agent-attachments/{targetAgentId}

Action Chain Attachments

Attach workflow automation chains to agents.

List Action Chains 

GET /orgs/{organizationId}/agents/{id}/chains

Response:

{
  "organizationId": "org-123",
  "agentId": "agent-456",
  "actionChains": [
    {
      "organizationId": "org-123",
      "agentId": "agent-456",
      "actionChainId": "chain-789",
      "name": "Order Processing",
      "createdAt": "2024-01-01T00:00:00Z"
    }
  ]
}

Attach Action Chain 

POST /orgs/{organizationId}/agents/{id}/chains

Request Body:

{
  "actionChainId": "chain-789"
}

Detach Action Chain 

DELETE /orgs/{organizationId}/agents/{id}/chains/{actionChainId}

Available Tools

List Available Tools 

GET /orgs/{organizationId}/tools

Returns all tools available for attachment to agents.

Agent Configuration Details

creativityScore

The creativityScore field controls response variability (similar to temperature):

  • String value between "0" and "1"
  • "0" - Deterministic, focused responses
  • "0.4" - Balanced (default)
  • "1" - Maximum creativity and variability

Email Integration

Agents can be configured to receive and process emails:

{
  "emailAddress": "support@yourdomain.com",
  "emailFilters": "all",
  "emailAttachmentsToKnowledgeBaseId": "kb-123",
  "emailAttachmentsFileTypeFilter": "pdf,docx,txt",
  "emailCcTo": "team@example.com,manager@example.com",
  "emailBccTo": "archive@example.com",
  "emailReplyTo": "noreply@example.com"
}

Email Configuration Fields:

  • emailAddress: Email address where agent receives messages
  • emailFilters: String value controlling access
    • "all" - All users in organization can send emails to this agent
    • Other values - Only users with explicit agent access can send emails
  • emailAttachmentsToKnowledgeBaseId: Knowledge base ID where email attachments are stored
  • emailAttachmentsFileTypeFilter: Comma-separated list of allowed file extensions (e.g., "pdf,docx,txt")
  • emailCcTo: Comma-separated list of email addresses to CC on agent replies
  • emailBccTo: Comma-separated list of email addresses to BCC on agent replies
  • emailReplyTo: Reply-To header for agent email responses

Behavior:

  • Incoming emails create new conversations with the agent
  • Attachments are automatically uploaded to the specified knowledge base
  • Agent can access attachment contents through knowledge base search
  • Agent replies are sent from the configured email address
  • File type filter restricts which attachment types are processed

Best Practices

  1. Clear Instructions - Provide detailed, specific instructions for your agent’s behavior
  2. Appropriate Model Selection - Choose models based on task complexity and cost requirements
  3. Creativity Score - Use lower values (0-0.3) for factual tasks, higher (0.7-1.0) for creative tasks
  4. Incremental Attachments - Test agents with one attachment at a time before adding more
  5. Monitor Usage - Track agent performance and token usage through analytics
  6. Required Fields - All fields (name, description, instructions, model) are required for both create and update
Conversations