---
title: "Create agent"
method: POST
path: "/agents"
tags: ["Agents"]
---

# Create agent

`POST /agents`

Create a new agent. The authenticated caller must have permission to create agents on the target team.

## Request body

- object
  - `name` string, required — Display name for the agent.
  - `model_name` string, required — ID of the LLM the agent runs on. Use `GET /models` to discover valid values.
  - `description` string, nullable
  - `system_prompt` string, nullable
  - `tools` object[] — Tools the agent can call. Each tool is an object whose shape depends on the tool type.
  - `resources` object[] — Resources attached to the agent.
  - `skill_ids` string[], nullable — IDs of skills to attach to the agent. Attachment happens inside the create transaction, so an invalid ID fails the whole request (no orphaned agent). Omit to attach none. The caller must hold `INVOKE` on each skill. After creation, manage skills with `PATCH /agents/{agent_id}/skills`.
  - `metadata` object, nullable — Arbitrary key/value metadata stored on the agent.
  - `folder_id` string, nullable — ID of the folder to place the agent in.
  - `is_active` boolean — Whether the agent is active. Defaults to `true`.
  - `agent_id` string, nullable — Optional caller-supplied agent ID. When omitted, the server generates one.
  - `team_id` string, nullable — ID of the team to create the agent under. When omitted, the agent is owned by the authenticated user.

## Response `201`

Agent created.

- object
  - `agent` object
    - `id` string — Unique agent identifier.
    - `name` string
    - `description` string, nullable
    - `team_id` string — ID of the team that owns the agent.
    - `is_active` boolean
    - `tools` object[] — Tools the agent can call. Secret references are stripped and MCP server URLs are redacted before being returned.
    - `metadata` object
    - `model_name` string, nullable — ID of the LLM the agent runs on.
    - `system_prompt` string, nullable
    - `resources` object[]
    - `skill_ids` string[], nullable — IDs of skills attached to the agent. `null` on surfaces that don't include them (e.g. the list endpoint); `[]` when none are attached. Manage with `PATCH /agents/{agent_id}/skills`.
    - `folder_id` string, nullable
    - `type` string, nullable — Internal agent type discriminator.
    - `created_at` string, date-time, nullable — ISO 8601 timestamp of when the agent was created.
    - `active_trigger_count` integer, nullable — Number of active triggers on this agent. Populated on list responses; may be `null` here.
    - `creator` object, nullable — User who created the agent. `null` when the creator is not known.
      - `id` string, nullable
      - `first_name` string, nullable
      - `last_name` string, nullable
      - `email` string, nullable
      - `profile_picture` string, nullable

## Other responses

- `400` — Invalid request body.
- `401` — Unauthorized — missing or invalid API key.
- `403` — Forbidden — the caller does not have permission to create agents on the requested team.
- `500` — Internal server error.

---

[API](https://skmtc.dev/gumloop/apis/public-api.md) · [All operations](https://skmtc.dev/gumloop/apis/public-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/gumloop/public-api/revisions/115f2d6ce387/schema)