--- title: "POST /v1/projects/{projectsId}/locations/{locationsId}/agents" method: POST path: "/v1/projects/{projectsId}/locations/{locationsId}/agents" tags: ["projects"] --- # POST /v1/projects/{projectsId}/locations/{locationsId}/agents `POST /v1/projects/{projectsId}/locations/{locationsId}/agents` ## Request - Base URL: `https://aiplatform.googleapis.com` - URL: `https://aiplatform.googleapis.com/v1/projects/{projectsId}/locations/{locationsId}/agents` - Auth: one of: - OAuth 2 and OAuth 2 - Implicit: `https://accounts.google.com/o/oauth2/auth` - Scopes: `https://www.googleapis.com/auth/aiplatform` - Authorization code: `https://accounts.google.com/o/oauth2/auth` - Token URL: `https://accounts.google.com/o/oauth2/token` scopes: `https://www.googleapis.com/auth/aiplatform` - OAuth 2 and OAuth 2 - Implicit: `https://accounts.google.com/o/oauth2/auth` - Scopes: `https://www.googleapis.com/auth/cloud-platform` - Authorization code: `https://accounts.google.com/o/oauth2/auth` - Token URL: `https://accounts.google.com/o/oauth2/token` scopes: `https://www.googleapis.com/auth/cloud-platform` Creates an agent. ## Path parameters - `projectsId` string, required - `locationsId` string, required ## Request body - GoogleCloudAiplatformV1Agent: A Vertex agent contains instructions and configurations for the LLM to execute a certain task. - `agentIdentity` GoogleCloudAiplatformV1AgentIdentity: Identity configuration for an agent. - `email` string: Optional. The email address representing the agent's principal identity. For Google Workspace agents, the email should be on a verified customer domain. - `gaiaId` string: Output only. The agent's own obfuscated Gaia id. Set only for an A2 (CoWorker) agent, which is the only kind that has a first-class Gaia account of its own. An A1 (Personal) agent has no `AgentIdentity` at all: it acts on behalf of its owner, so the identity it runs as is `Agent.owner`, and there is no separate Gaia account to name. Populated asynchronously once the agent identity is provisioned, so it may be absent from the `CreateAgent` LRO response and present on `GetAgent`/`ListAgents`. - `tenant` GoogleCloudAiplatformV1Tenant: Represents an enterprise tenant. - `id` string: Optional. The unique raw ID of the tenant. - `type` 'TYPE_UNSPECIFIED' | 'WORKSPACE_CUSTOMER': Optional. The type of the tenant. - `aiApplication` string: Output only. The resource name of the AI Application provisioned for this agent. Format: `projects/{project}/locations/{location}/aiApplications/{ai_application}`. - `allowedTeammates` GoogleCloudAiplatformV1AllowedTeammates: The set of identities an agent is allowed to contact outbound -- who the agent may talk to, not who may talk to the agent (that is IAM's job). The membership is stored on the agent, so the Agents API is authoritative for what this field reports. - `teammates` GoogleCloudAiplatformV1Teammate[]: Optional. The teammates the agent is permitted to contact. At most 500. OUTPUT: always returned. An empty list means the agent has no teammates, not that the field went unread. INPUT: the complete desired set, not a delta -- teammates absent from it are removed. The backing roster is updated asynchronously and best-effort after the write returns, so it may briefly lag what `GetAgent` reports. What the agent is actually able to reach follows the roster, not this field, until the two converge. - `email` string: Optional. Email address of the teammate. - `expansionMode` 'EXPANSION_MODE_UNSPECIFIED' | 'INFER' | 'EXPANDED' | 'NON_EXPANDED': Optional. Expansion mode for group or space teammates. - `gaiaId` string: Optional. Obfuscated Gaia id of the teammate. OBFUSCATED, never a raw Gaia id -- the same form as `Principal.id` and every other Gaia id this API surfaces, so the two are comparable. A string rather than an int64 for that reason: the obfuscated form is not a number. - `base_agent` string: Required. Immutable. The base agent for the agent. Supported values: * `antigravity-preview-05-2026` Immutable: `UpdateAgent` rejects a change, including clearing it. The kind of agent this is gets derived from this field when the agent is created and is recorded then; nothing recomputes it afterwards, so a later change would leave the agent described as one kind and behaving as another. Create a new agent instead. - `base_environment` unknown - `created` string, google-datetime: Output only. The time the agent was created. - `description` string: Optional. The description of the agent. - `effectiveIdentity` string: Output only. The resolved Agent Identity (SPIFFE principal) of the agent. - `encryptionSpec` GoogleCloudAiplatformV1EncryptionSpec: Represents a customer-managed encryption key specification that can be applied to a Vertex AI resource. - `kmsKeyName` string: Required. Resource name of the Cloud KMS key used to protect the resource. The Cloud KMS key must be in the same region as the resource. It must have the format `projects/{project}/locations/{location}/keyRings/{key_ring}/cryptoKeys/{crypto_key}`. - `id` string: Immutable. The user-specified ID for the agent. This ID becomes the final component of the agent resource name. If not provided, Vertex AI will generate a value for this ID. The ID can be up to 63 characters and must match the regular expression `[a-z]([a-z0-9-]{0,61}[a-z0-9])?`. - `memoryConfig` GoogleCloudAiplatformV1AgentMemoryConfig: Agent-level memory settings. These apply across every task the agent runs and every user of the agent: this is an agent-wide control, not a per-user one. To turn memory off for a single end user of a shared agent, the calling surface sets `TaskSpec.scope.memory_config.disable_memory` on that user's tasks. - `disableMemory` boolean: Optional. If true, memory is disabled for the agent as a whole: across every task it runs, the agent neither reads existing memories into the prompt nor forms new ones. Memory is on by default, and this is the setting that wins. A task may turn memory off for itself alone with `TaskSpec.scope.memory_config.disable_memory`, but cannot turn it back on while this is true; the two are OR'ed. This level wins because it is the mutable one. Turning it on has to cover the tasks that already exist, whose stored specs still say whatever they were created with, so the agent's current value is re-applied every time a session opens, including on a resume. Memories already stored are retained and stay readable by the agent's users; this governs only whether the agent can access and modify them. - `metadata` object: Optional. The metadata for the agent. - `modelConfig` GoogleCloudAiplatformV1AgentModelConfig: Selects the model configuration for an agent. Starts with just the model id/alias; extensible with further model parameters without a breaking change. - `model` string: Optional. Publisher model resource name (an `aiplatform.googleapis.com/PublisherModel`) of the form "publishers/{publisher}/models/{model}", e.g. "publishers/anthropic/models/claude-opus-4-8" or "publishers/google/models/gemini-3-flash". Empty means the agent's default gemini model. - `temperature` number, float: Optional. Sampling temperature for the model's generation config (valid range (0.0, 2.0]); a value outside that range leaves the backend default standing. - `name` string: Identifier. The resource name of the agent. Format: `projects/{project}/locations/{location}/agents/{agent}`. - `object` string: Output only. The object type of the resource. For agents, the value is `agent`. - `observabilityConfig` GoogleCloudAiplatformV1ObservabilityConfig: Observability settings for one agent's sessions. - `observabilityEnabled` boolean: Optional. Enables observability for this agent's sessions: OpenTelemetry span emission covering tool names, model names, token counts, latencies and status. If `false`, the other fields here are ignored. - `sensitiveLoggingEnabled` boolean: Optional. Enables sensitive logging. Sensitive logging includes customer core content (prompts, model completions, tool argument payloads and tool responses). If `false`, those are sanitized and only structural attributes are recorded. No effect unless `observability_enabled` is true. Settable and returned, but NOT YET ENFORCED. Nothing reads it at runtime, so `true` does not currently cause content to be captured, and `false` is not what keeps content from being captured. Treat it as a recorded intention that takes effect when enforcement lands. - `owner` GoogleCloudAiplatformV1Principal: Represents an identity principal (user or service). - `id` string: Optional. The system unique identifier of the principal. - `type` 'TYPE_UNSPECIFIED' | 'USER': Optional. The type of the principal. - `persona` GoogleCloudAiplatformV1Persona: The persona (presentation) of an agent. - `avatarUrl` string: Optional. The URL of the agent's avatar. - `displayName` string: Required. The display name of the agent. - `personality` string: Optional. The personality style or behavioral trait of the agent. - `role` string: Optional. The role of the agent (e.g., "Financial Analyst"). - `status` GoogleCloudAiplatformV1AgentStatus: Operational state of the agent. - `deleteTime` string, google-datetime: Output only. The time at which the agent was soft-deleted. - `state` 'STATE_UNSPECIFIED' | 'ACTIVE' | 'SUSPENDED' | 'ARCHIVED' | 'DELETED': Output only. The current state of the agent. - `suspensionReason` GoogleCloudAiplatformV1AgentStatusSuspensionReason: Details about the active suspension. This message is only populated if the state is SUSPENDED. - `reason` 'REASON_UNSPECIFIED' | 'ABUSE' | 'ADMIN' | 'USER_INITIATED': Output only. The reason for the current suspension. - `suspensionTime` string, google-datetime: Output only. The time when the current suspension was applied. - `system_instruction` string: Optional. The instructions for the agent to follow. These instructions are passed to the LLM as a system instruction. - `tools` GoogleCloudAiplatformV1AgentTool[]: Optional. The tools available to the agent. - `headers` object: Optional. The headers for the MCP server, such as for authentication. Only applicable when `type` is `mcp_server`. - `name` string: Optional. The tool's Google Cloud resource name, used to resolve the tool. Applicable when `type` is `mcp_server` or `endpoint` (a tool registered in Agent Registry), for example `projects/{project}/locations/{location}/.../mcpServers/{id}` or `projects/{project}/locations/{location}/.../endpoints/{id}`. - `type` string: Required. The type of the tool. Supported types: * `audio_generation` * `code_execution` * `endpoint` * `filesystem` * `google_search` * `image_generation` * `mcp_server` * `speech_generation` * `url_context` * `video_generation` - `url` string: Optional. Fallback for the tool's runtime reference, consumed by `CreateAgent` to create the downstream AI App. Applicable when `type` is `mcp_server` or `endpoint`, and optional: the Agent service derives the runtime reference from `name` via Agent Registry (`GetMcpServer` / `GetEndpoint`), and reads this only when that lookup yields none. - `updated` string, google-datetime: Output only. The time the agent was last updated. ## Response `200` Successful response - GoogleLongrunningOperation: This resource represents a long-running operation that is the result of a network API call. - `done` boolean: If the value is `false`, it means the operation is still in progress. If `true`, the operation is completed, and either `error` or `response` is available. - `error` GoogleRpcStatus: The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors). - `code` integer: The status code, which should be an enum value of google.rpc.Code. - `details` object[]: A list of messages that carry the error details. There is a common set of message types for APIs to use. - `message` string: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the google.rpc.Status.details field, or localized by the client. - `metadata` object: Service-specific metadata associated with the operation. It typically contains progress information and common metadata such as create time. Some services might not provide such metadata. Any method that returns a long-running operation should document the metadata type, if any. - `name` string: The server-assigned name, which is only unique within the same service that originally returns it. If you use the default HTTP mapping, the `name` should be a resource name ending with `operations/{unique_id}`. - `response` object: The normal, successful response of the operation. If the original method returns no data on success, such as `Delete`, the response is `google.protobuf.Empty`. If the original method is standard `Get`/`Create`/`Update`, the response should be the resource. For other methods, the response should have the type `XxxResponse`, where `Xxx` is the original method name. For example, if the original method name is `TakeSnapshot()`, the inferred response type is `TakeSnapshotResponse`. ## Changes - **2026-11-06** `3aca3b348f0c`: 4 info - the security scope `https://www.googleapis.com/auth/aiplatform` was added to the endpoint's security scheme `Oauth2` - the security scope `https://www.googleapis.com/auth/aiplatform` was added to the endpoint's security scheme `Oauth2c` - the security scope `https://www.googleapis.com/auth/cloud-platform` was removed from the endpoint's security scheme `Oauth2` - the security scope `https://www.googleapis.com/auth/cloud-platform` was removed from the endpoint's security scheme `Oauth2c` - **2026-10-30** `34fcc627b062`: 1 warning, 4 info - deleted the `query` request parameter `idpNonce` - the security scope `https://www.googleapis.com/auth/aiplatform` was added to the endpoint's security scheme `Oauth2` - the security scope `https://www.googleapis.com/auth/aiplatform` was added to the endpoint's security scheme `Oauth2c` - the security scope `https://www.googleapis.com/auth/cloud-platform` was removed from the endpoint's security scheme `Oauth2` - …1 more [Operation history](https://skmtc.dev/google/apis/aiplatform/changes/v1/projects/:projectsId/locations/:locationsId/agents/post.md) --- [API](https://skmtc.dev/google/apis/aiplatform.md) - [All operations](https://skmtc.dev/google/apis/aiplatform/llms.txt) - [OpenAPI document](https://skmtc.dev/google/apis/aiplatform/revisions/3aca3b348f0c?raw)