> For the complete documentation index, see [llms.txt](https://docs.ibexa.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ibexa.ai/developers/rest-api/agents/update-agent.md).

# Update Agent

Update agent.

Users can only update agents they created within their organisation.

```json
{"openapi":"3.1.0","info":{"title":"Ibexa Agentic Marketing Platform","version":"0.1.0"},"security":[{"OAuth2PasswordBearer":[]}],"components":{"securitySchemes":{"OAuth2PasswordBearer":{"type":"oauth2","flows":{"password":{"scopes":{},"tokenUrl":"/api/v1/login/access-token"}}}},"schemas":{"UpdateAgentPayloadSchema":{"properties":{"name":{"type":"string","title":"Name"},"identifier":{"type":"string","title":"Identifier"},"instruction":{"type":"string","title":"Instruction"},"is_enabled":{"type":"boolean","title":"Is Enabled"},"can_be_subagent":{"type":"boolean","title":"Can Be Subagent"},"budget":{"$ref":"#/components/schemas/BudgetSchema","description":"Agent budget in credits. Required on update: this is a full replacement, so the budget must be restated every time — an existing cap must never be lifted by omitting the field."},"description":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"title":"Description"},"language_model_provider_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Language Model Provider Id"},"model_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Model Id"},"input_schema":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Input Schema","description":"JSON Schema describing the expected input structure for this agent."},"output_schema":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Output Schema","description":"JSON Schema describing the expected output structure for this agent."},"knowledge_base_scope":{"$ref":"#/components/schemas/KnowledgeBaseScope","description":"Knowledge-base access: 'none', 'all', or 'branch'. Required on update: this is a full replacement, so the scope must be restated every time — an agent's access must never change by omitting the field.","default":"none"},"knowledge_base_node_ids":{"items":{"type":"integer","exclusiveMinimum":0},"type":"array","title":"Knowledge Base Node Ids","description":"Folder node ids to confine the agent to. Required (one or more) when scope is 'branch'; must be omitted for 'none' or 'all'."},"eval_config":{"anyOf":[{"$ref":"#/components/schemas/EvalConfigSchema"},{"type":"null"}],"description":"Metrics this agent is evaluated against, with per-metric thresholds and weights."},"graph_recursion_limit":{"anyOf":[{"type":"integer","maximum":100,"exclusiveMinimum":0},{"type":"null"}],"title":"Graph Recursion Limit","description":"Per-agent override for the LangGraph recursion limit (max steps in the tool-calling loop). Must not exceed the platform cap (100). If null, LangGraph's own default (25) is used."},"agents_catalog_entry_id":{"anyOf":[{"type":"integer","exclusiveMinimum":0},{"type":"null"}],"title":"Agents Catalog Entry Id","description":"Optional reference to the agents catalog entry this agent was created from. Used to track catalog template popularity."},"impact_metric":{"anyOf":[{"$ref":"#/components/schemas/ImpactMetricSchema"},{"type":"null"}],"description":"The impact (ROI) one run of this agent generates. This is a full replacement: omitting the field clears any existing impact metric, it does not leave it unchanged."}},"type":"object","required":["name","identifier","instruction","is_enabled","can_be_subagent","budget"],"title":"UpdateAgentPayloadSchema","description":"Pydantic schema for updating an agent."},"BudgetSchema":{"properties":{"scope":{"$ref":"#/components/schemas/BudgetScope","description":"Budget scope: 'limited' (capped at 'amount' credits) or 'unlimited' (uncapped, the default).","default":"unlimited"},"amount":{"type":"integer","minimum":0,"title":"Amount","description":"Budget amount in whole credits. Required when scope is 'limited'; must be 0 (or omitted) when scope is 'unlimited'.","default":0},"currency":{"type":"string","const":"credits","title":"Currency","description":"Always 'credits' — agent budgets are denominated in the platform's virtual currency only.","default":"credits"}},"type":"object","title":"BudgetSchema","description":"Agent budget, denominated in credits.\n\nAn uncapped budget is the named scope 'unlimited', never a null budget or a\nnegative amount — a cap can only be lifted by saying so. Requests may omit\nthe whole budget (it defaults to unlimited), but never `amount` on a\n'limited' budget: a missing cap must not silently become zero credits."},"BudgetScope":{"type":"string","enum":["limited","unlimited"],"title":"BudgetScope","description":"Whether an agent's credit spend is capped.\n\nAn uncapped budget is a positive, named value (`UNLIMITED`) — never a\nnegative amount, an empty currency, or a missing field — so a cap can never\nbe lifted by a value that merely looks absent. Callers branch on\n`is_limited` / `is_unlimited`, never on the amount."},"KnowledgeBaseScope":{"type":"string","enum":["none","all","branch"],"title":"KnowledgeBaseScope","description":"How much of the organisation's knowledge base an agent may access.\n\nThe default is `NONE` (no access): access is a deliberate opt-in, so linking\nthe knowledge-base tools to an agent never silently grants the whole KB.\nWhole-KB access is a positive, named value (`ALL`) — never the absence of a\nbranch — so it can never be granted by a forgotten field. Enforcement branches\non `is_none` / `is_all` / `is_branch`, never on whether a node id happens to be\nset."},"EvalConfigSchema":{"properties":{"metrics":{"items":{"$ref":"#/components/schemas/EvalMetricConfigSchema"},"type":"array","title":"Metrics"},"sample_size":{"type":"number","maximum":100,"minimum":0,"title":"Sample Size","description":"Percentage of eligible runs that actually get evaluated.","default":100}},"type":"object","title":"EvalConfigSchema","description":"Pydantic schema for an agent's full evaluation configuration."},"EvalMetricConfigSchema":{"properties":{"metric_id":{"type":"string","maxLength":100,"minLength":1,"title":"Metric Id"},"threshold":{"type":"number","minimum":0,"title":"Threshold","description":"The value this metric must reach to pass, in the metric's own unit/scale (e.g. 80.0 for an 80% success_rate, 5.0 for a 5-second latency cap, 0.7 for a 0.0-1.0 correctness score). Check GET /metric-providers/types for this metric_id's `unit` and `is_maximized` before choosing a threshold."},"weight":{"type":"number","maximum":1,"minimum":0,"title":"Weight","description":"This metric's contribution to the overall quality score."},"config":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Config","description":"Metric-specific settings, e.g. a custom rubric or expected-tools list."},"is_gate":{"type":"boolean","title":"Is Gate","description":"If true, the other configured metrics are skipped whenever this one fails.","default":false},"is_maximized":{"type":"boolean","title":"Is Maximized","description":"Only consulted for ad-hoc/custom-rubric metrics with no registered definition (e.g. config.rubric metrics like 'verbosity' where a LOW score should pass). Ignored for any metric_id with a registered EvaluationMetric — its intrinsic direction always wins (check GET /metric-providers/types).","default":true}},"type":"object","required":["metric_id","threshold","weight"],"title":"EvalMetricConfigSchema","description":"Pydantic schema for one metric's evaluation configuration."},"ImpactMetricSchema":{"properties":{"metric_type":{"type":"string","maxLength":50,"minLength":1,"title":"Metric Type","description":"Kind of impact this agent generates per run, e.g. 'Saved time', 'Saved money', 'Resolved issues', 'New leads'."},"value":{"type":"integer","minimum":0,"title":"Value","description":"Impact generated per run, denominated in 'unit'."},"unit":{"type":"string","maxLength":20,"minLength":1,"title":"Unit","description":"Unit 'value' is denominated in, e.g. 'min', 'hours', 'EUR', 'leads'."}},"type":"object","required":["metric_type","value","unit"],"title":"ImpactMetricSchema","description":"The impact (ROI) one run of the agent generates.\n\nAll three fields are required together — there is no partial state such as\na value with no unit. An agent with no impact metric configured omits this\nfield entirely (or sends it as `null`) rather than sending a partial object."},"UpdateAgentResponseSchema":{"properties":{"id":{"type":"integer","title":"Id"},"organisation_id":{"type":"integer","title":"Organisation Id"},"name":{"type":"string","title":"Name"},"identifier":{"type":"string","title":"Identifier"},"instruction":{"type":"string","title":"Instruction"},"is_enabled":{"type":"boolean","title":"Is Enabled"},"can_be_subagent":{"type":"boolean","title":"Can Be Subagent"},"budget":{"$ref":"#/components/schemas/BudgetSchema","description":"Agent budget in credits. Always present; an uncapped budget is the scope 'unlimited'."},"created_by":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Created By"},"description":{"anyOf":[{"type":"string","maxLength":1000},{"type":"null"}],"title":"Description"},"language_model_provider_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Language Model Provider Id"},"model_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Model Id"},"is_model_valid":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Model Valid"},"input_schema":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Input Schema","description":"JSON Schema describing the expected input structure for this agent."},"output_schema":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Output Schema","description":"JSON Schema describing the expected output structure for this agent."},"knowledge_base_scope":{"$ref":"#/components/schemas/KnowledgeBaseScope","description":"Knowledge-base access: 'none' (no access), 'all' (whole knowledge base), or 'branch' (one or more folder subtrees)."},"knowledge_base_node_ids":{"items":{"type":"integer"},"type":"array","title":"Knowledge Base Node Ids","description":"Folder nodes the agent's knowledge-base access is confined to. Non-empty only when scope is 'branch'."},"eval_config":{"anyOf":[{"$ref":"#/components/schemas/EvalConfigSchema"},{"type":"null"}],"description":"Metrics this agent is evaluated against, with per-metric thresholds and weights."},"graph_recursion_limit":{"anyOf":[{"type":"integer","maximum":100,"exclusiveMinimum":0},{"type":"null"}],"title":"Graph Recursion Limit","description":"Per-agent override for the LangGraph recursion limit (max steps in the tool-calling loop). Must not exceed the platform cap (100). If null, LangGraph's own default (25) is used."},"agents_catalog_entry_id":{"anyOf":[{"type":"integer","exclusiveMinimum":0},{"type":"null"}],"title":"Agents Catalog Entry Id","description":"Optional reference to the agents catalog entry this agent was created from. Used to track catalog template popularity."},"impact_metric":{"anyOf":[{"$ref":"#/components/schemas/ImpactMetricSchema"},{"type":"null"}],"description":"The impact (ROI) one run of this agent generates. Null when no impact metric is configured."}},"type":"object","required":["id","organisation_id","name","identifier","instruction","is_enabled","can_be_subagent","budget","created_by","knowledge_base_scope"],"title":"UpdateAgentResponseSchema","description":"Pydantic schema for agent update response."}}},"paths":{"/api/v1/agents/{agent_id}":{"put":{"tags":["agents","public"],"summary":"Update Agent","description":"Update agent.\n\nUsers can only update agents they created within their organisation.","operationId":"agents-update_agent","parameters":[{"name":"agent_id","in":"path","required":true,"schema":{"type":"integer","title":"Agent Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateAgentPayloadSchema"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateAgentResponseSchema"}}}},"400":{"description":"Invalid request payload or parameters","content":{"application/json":{}}},"401":{"description":"User not authenticated","content":{"application/json":{}}},"403":{"description":"User lacks permission","content":{"application/json":{}}},"404":{"description":"Resource not found or user has no permission to access it","content":{"application/json":{}}}}}}}}
```