Find or create a personal agent
Idempotently provision a PERSONAL agent for a user. Returns the existing agent if one already exists for the (app, user) pair. Requires permission agents:write.
v2 compatibility notes
(app, user) pair has already been provisioned. The operation is idempotent — calling it multiple times with the same application and user always returns the same agent. The HTTP status code distinguishes create from find: 201 Created on first provision, 200 OK when returning an existing agent.
Uniqueness is enforced per (principalExternalApplicationId, userId, agentType=PERSONAL) — one personal agent per app-user pair. The principalExternalApplicationId is always derived server-side from the bearer token.
Request
Headers
Body
name, description, model, prompt, etc.) are applied only when the agent is first created. If an agent already exists for the (app, user) pair, the endpoint returns the existing record without modification. To update an existing agent’s definition, use the management API’s PATCH /api/v2/agents/update endpoint.User identity resolution
The endpoint resolves the user through one of two paths, tried in order: 1.X-Forge-User-JWT header (preferred)
Pass the JWT your application issued for the current user. Forge validates it against your application’s JWKS configuration and JIT-provisions a Forge user record if the user has never been seen before. The resulting Forge userId is used as the personal agent’s owner.
This is the right path for first-time user provisioning. After the first call, the response includes the userId — you can cache it and use the explicit body param path on subsequent calls.
2. Explicit userId in body
Pass the Forge userId directly. This path is find-only: Forge verifies the user exists, was provisioned as an external user (not a Forge employee or another internal account type), is active, and was provisioned under your application specifically — not a different external application that happens to know the same userId. Returns 404 Not Found if the user has never been provisioned, or 403 Forbidden if any of the other checks fail — use the JWT path to provision a user before referencing them this way.
If neither X-Forge-User-JWT nor userId is provided, the endpoint returns 400 Bad Request.
Response
201 Created — agent provisioned
200 OK — existing agent returned
Same shape as 201. The_id, agentId, and createdAt fields reflect the original creation values.
Response fields
principalExternalApplicationId or principalKind. These are internal governance fields — your application already knows its own ID from the bearer token, and echoing them in the response would add no information.Errors
Example
See also
- List available models for an agent — discover what models the provisioned agent can use
- Talk to Agents — the Personal Agent model from the console perspective
- External App API overview — auth and domain context
Authorizations
Headers
1–255 printable ASCII characters (0x21–0x7E, no spaces), scoped to the calling credential. A repeat with the same key and request never runs the write again, a 5xx included: once the operation's permissions pass again it answers the identical status and body of the first response (Idempotent-Replayed: true, also sent as Idempotency-Replayed: true), unless the operation's own replay policy withholds it; a first response that was not stored (over 32 KiB, or carrying a one-time secret) answers its first status with only data.id (Idempotency-Replay-Disclosure: id-only) when it named one; otherwise 409 idempotency_result_unavailable; a repeat while the first is still running is 409 idempotency_key_in_flight, and the same key with a different request is 422 idempotency_key_reuse. Honoured for External App JWTs and platform and Personal keys; an External App's static companion key is not protected.
1 - 255
