> ## Documentation Index > Fetch the complete documentation index at: https://docs.cerca.dev/llms.txt > Use this file to discover all available pages before exploring further. # Create agent ## OpenAPI ````yaml https://app.stainless.com/api/spec/documented/cerca/openapi.documented.yml post /agents openapi: 3.1.0 info: description: API-key accessible routes for Cerca agents. title: Cerca API version: 0.0.0 servers: - url: https://api.cerca.dev security: - bearerAuth: [] paths: /agents: post: tags: - Agents summary: Create agent requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateAgentRequest' responses: '201': description: Agent created. content: application/json: schema: $ref: '#/components/schemas/Agent' '400': description: Invalid runtime request. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Authentication required. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: >- Access denied or non-transient quota exceeded. Limit errors include a stable code field. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Runtime resource not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: >- Transient capacity limit exceeded. Limit errors include a stable code field. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '503': description: Required runtime dependency unavailable. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' default: description: Runtime error response. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - bearerAuth: [] x-codeSamples: - lang: JavaScript source: |- import Cerca from '@cerca-dev/sdk'; const client = new Cerca({ apiKey: process.env['CERCA_API_KEY'], // This is the default and can be omitted }); const agent = await client.agents.create(); console.log(agent.id); - lang: Python source: |- import os from cerca import Cerca client = Cerca( api_key=os.environ.get("CERCA_API_KEY"), # This is the default and can be omitted ) agent = client.agents.create() print(agent.id) - lang: Go source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/matrices/cerca-go\"\n\t\"github.com/matrices/cerca-go/option\"\n)\n\nfunc main() {\n\tclient := cercago.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\tagent, err := client.Agents.New(context.TODO(), cercago.AgentNewParams{})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", agent.ID)\n}\n" - lang: Ruby source: |- require "cerca" cerca = Cerca::Client.new(api_key: "My API Key") agent = cerca.agents.create puts(agent) - lang: CLI source: |- cerca agents create \ --api-key 'My API Key' components: schemas: CreateAgentRequest: type: object properties: configuration: $ref: '#/components/schemas/AgentConfiguration' fleetId: type: string metadata: $ref: '#/components/schemas/AgentMetadata' userId: type: string additionalProperties: x-stainless-any: true Agent: type: object properties: configuration: $ref: '#/components/schemas/AgentConfiguration' createdAt: type: string effective: $ref: '#/components/schemas/EffectiveConfiguration' fleetId: type: string executionPrincipal: oneOf: - $ref: '#/components/schemas/ExecutionPrincipal' - type: 'null' id: type: string metadata: $ref: '#/components/schemas/AgentMetadata' orgId: type: string updatedAt: type: string userId: type: string required: - configuration - createdAt - fleetId - executionPrincipal - id - metadata - orgId - updatedAt - userId ErrorResponse: type: object properties: error: type: string code: type: string description: Stable machine-readable error code when the API can provide one. example: MONTHLY_TOKEN_BUDGET_EXCEEDED required: - error AgentConfiguration: type: object properties: approvals: $ref: '#/components/schemas/ApprovalPolicy' defaultModel: type: string instructions: type: string tools: type: array items: $ref: '#/components/schemas/RuntimeToolSpec' description: >- Agent tool allowlist. These tools are subject to fleet defaults and locks, and thread or turn requests may only narrow the resulting effective tools. AgentMetadata: type: object additionalProperties: type: string description: >- Arbitrary string metadata stored on an agent. Runtime enforces maximum key and value sizes. example: project: alpha EffectiveConfiguration: type: object properties: approvals: type: object properties: tools: type: object additionalProperties: $ref: '#/components/schemas/RuntimeApprovalPolicyMode' timeoutMs: type: number required: - tools - timeoutMs approvalsWritableByAgent: type: boolean defaultModel: type: string instructions: type: string lockedByFleet: type: array items: $ref: '#/components/schemas/ConfigurationFieldName' resolvedFromFleet: type: array items: $ref: '#/components/schemas/ConfigurationFieldName' tools: type: array items: $ref: '#/components/schemas/RuntimeToolName' description: >- Effective internal runtime tools after applying fleet defaults, fleet locks, and the agent allowlist. required: - approvals - approvalsWritableByAgent - defaultModel - lockedByFleet - resolvedFromFleet - tools ExecutionPrincipal: oneOf: - type: object properties: kind: type: string enum: - user x-stainless-const: true userId: type: string required: - kind - userId title: UserExecutionPrincipal x-stainless-variantName: UserExecutionPrincipal - type: object properties: fleetId: type: - string - 'null' keyId: type: string kind: type: string enum: - apiKey x-stainless-const: true required: - fleetId - keyId - kind title: ApiKeyExecutionPrincipal x-stainless-variantName: ApiKeyExecutionPrincipal discriminator: propertyName: kind ApprovalPolicy: type: object properties: tools: type: object additionalProperties: $ref: '#/components/schemas/RuntimeApprovalPolicyMode' timeoutMs: type: number RuntimeToolSpec: type: string minLength: 1 description: >- Configurable runtime tool name, configurable namespace wildcard such as sandbox.*, or external namespace wildcard such as google.*. At thread and turn scope, entries can only narrow the agent's effective tools. examples: - sandbox.* - memory.read - google.* RuntimeApprovalPolicyMode: type: string enum: - always - never ConfigurationFieldName: type: string enum: - defaultModel - instructions - tools - approvals RuntimeToolName: type: string enum: - get_time - sub_thread - wait - tool.call - tool.discover - artifact.read - agent.threads.list - agent.threads.get - agent.approvals.cancel - agent.approvals.grant_thread - agent.approvals.grant_agent - agent.create - agent.approvals.update - tool.connect - sandbox.exec - sandbox.read - sandbox.write_file - sandbox.read_file - sandbox.spawn - sandbox.stdin - sandbox.session_read - sandbox.kill - sandbox.list_sessions - sandbox.sync_artifact - memory.read - memory.list - memory.search - memory.write - memory.delete - db.query - web.search - web.fetch - agent.schedule.list - agent.schedule.create - agent.schedule.update - agent.schedule.delete - agent.schedule.trigger securitySchemes: bearerAuth: bearerFormat: Cerca API key scheme: bearer type: http ````