---
title: "Create an agent in an environment"
method: POST
path: "/organization/{organization_id}/project/{project}/managed-agents/agent"
tags: ["Service:_Managed_Agents"]
---

# Create an agent in an environment

`POST /organization/{organization_id}/project/{project}/managed-agents/agent`

## Request

- Base URL: `https://api.aiven.io/v1`
- URL: `https://api.aiven.io/v1/organization/{organization_id}/project/{project}/managed-agents/agent`
- Auth: HTTP bearer and OAuth 2
  - Authorization code: `https://console.aiven.io/oauth/authorize`
  - Token URL: `https://api.aiven.io/v1/oauth2/token` scopes: `services:write`

> This endpoint **may be changed or removed at any time**. Don't use it in production environments.

## Path parameters

- `organization_id` string, required
- `project` string, required

## Request body

- ManagedAgentsAgentCreateRequestBody: ManagedAgentsAgentCreateRequestBody
  - `environment` string: Ignored today; the project's environment is resolved server-side.
  - `model` string, required: LLM model handle
  - `name` string, required: Agent name
  - `system_instructions` string: System instructions for the agent
  - `tool_ids` string[]: Tool IDs to attach (from MCP integration tools)

## Response `200`

Response

- ManagedAgentsAgentCreateResponse: ManagedAgentsAgentCreateResponse
  - `created_at` string: Created At
  - `id` string, required: Agent ID
  - `name` string, required: Agent name

## Other responses

- `403`: Operation not allowed
- `409`: Request conflict

## Changes

- **2026-10-12** `8bc631e52c97`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/aiven/apis/aiven-api-documentation/changes/organization/:organization_id/project/:project/managed-agents/agent/post.md)

---

[API](https://skmtc.dev/aiven/apis/aiven-api-documentation.md) - [All operations](https://skmtc.dev/aiven/apis/aiven-api-documentation/llms.txt) - [OpenAPI document](https://skmtc.dev/aiven/apis/aiven-api-documentation/revisions/b5ff8f3e4299?raw)