---
title: "Update an agent"
method: PATCH
path: "/v1/agents/{agent_id}"
tags: ["Agents"]
---

# Update an agent

`PATCH /v1/agents/{agent_id}`

Update an agent's draft graph in place.

You must be a member of the agent's organization. The agent's draft is replaced with the
supplied graph and re-validated, so you can iterate one draft — create, then update per
fix — instead of creating a new agent on every change. The response carries the updated
`validation`; publish with `POST /v1/agents/{agent_id}/publish` once `validation.valid`.

## Path parameters

- `agent_id` string, uuid, required — The ID of the agent to update.

## Request body

- UpdateAgentRequest — Request body for updating a draft agent's graph in place.
  - `graph` object, required — New workflow graph for the agent's draft version. Replaces the current draft graph; the agent is iterated in place rather than re-created, so its ID is stable. Required — a null graph is rejected as a 422 here rather than as a relayed upstream error.

## Response `200`

Successful Response

- AgentDetail — Detailed information for an agent.
  - `id` string, uuid, required — Unique ID for the agent.
  - `organization_id` string, uuid, required — Unique ID of the organization that owns the agent.
  - `name` string, required — Display name of the agent.
  - `status` 'draft' | 'published' | 'unknown', required — Current availability status for an agent.
  - `created_at` string, date-time, required — When the agent was created.
  - `description` string, nullable — Short description of the agent, if provided.
  - `schema` AgentSchema — Schema metadata for an agent.
    - `input` object, required — JSON Schema for the agent's `inputs` object. Use the top-level property keys as input field names when starting a run.
    - `output` object, required — JSON Schema for the `outputs` object returned by `GET /v1/agents/{agent_id}/runs/{run_id}`.
  - `validation` AgentValidation — Result of validating an agent's graph. Mirrors the report computed on every read, so callers can confirm a draft is publishable before calling publish.
    - `valid` boolean, required — Whether the agent's graph is valid and ready to publish.
    - `issues` AgentValidationIssue[] — Problems found while validating the graph. Empty when `valid` is true.
      - `code` string, required — Stable machine-readable identifier for the kind of issue.
      - `message` string, required — Human-readable description of the issue.
      - `node_id` string, nullable — ID of the node the issue applies to, if node-specific.
      - `node_title` string, nullable — Display title of the affected node, if available.
      - `field` string, nullable — Name of the offending field on the node, if field-specific.
      - `field_title` string, nullable — Display title of the affected field, if available.
      - `violation` string, nullable — The specific constraint that was violated, if available.

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/cooper-square-technologies/apis/external-api.md) · [All operations](https://skmtc.net/cooper-square-technologies/apis/external-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/cooper-square-technologies/external-api/revisions/ab03b3c80494/schema)