Create or Update Agent

Create or Update an Agent.

PUT /api/svc/v1/agents

Create or Update Agent

cURL

curl --request PUT \
  --url https://{controlPlaneURL}/api/svc/v1/agents \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "manifest": {
    "type": "agent/remote",
    "name": "<string>",
    "description": "<string>",
    "identity": {
      "type": "truefoundry-backed"
    },
    "proxy_via_gateway": {
      "enabled": true,
      "url": "<string>",
      "framework": {
        "type": "a2a",
        "agent_card_path": "/.well-known/agent-card.json"
      },
      "auth_data": {
        "type": "header",
        "headers": {}
      }
    },
    "display_name": "<string>",
    "state": "active",
    "collaborators": [
      {
        "subject": "<string>",
        "role_id": "<string>"
      }
    ],
    "tags": {}
  },
  "dryRun": false
}
'

200

{
  "data": {
    "agentId": "<string>",
    "fqn": "<string>",
    "manifest": {
      "type": "truefoundry-agent",
      "name": "<string>",
      "description": "<string>",
      "model": {
        "name": "<string>",
        "params": {
          "max_tokens": 1,
          "reasoning_effort": "<string>",
          "temperature": 1,
          "top_p": 0.5,
          "top_k": 1,
          "parallel_tool_calls": true
        }
      },
      "tags": {},
      "skills": [
        {
          "type": "truefoundry-skills-registry",
          "fqn": "<string>",
          "preload": false
        }
      ],
      "mcp_servers": [
        {
          "type": "truefoundry-mcp-registry",
          "name": "<string>",
          "preload": false,
          "enable_tools": [
            "@all"
          ],
          "disable_tools": [
            "<string>"
          ],
          "preload_tools": [
            "<string>"
          ],
          "require_approval_for_tools": [
            "@write",
            "@destructive"
          ]
        }
      ],
      "instructions": "<string>",
      "messages": [
        {
          "type": "user.message",
          "content": "<string>"
        }
      ],
      "variables": {},
      "sample_inputs": [
        {
          "text": "<string>",
          "variables": {}
        }
      ],
      "response_format": {
        "type": "text"
      },
      "config": {
        "iteration_limit": 100,
        "sandbox": {
          "enabled": true,
          "file_downloads": true,
          "network_policy": {
            "auth_inject": [
              {
                "type": "git",
                "match": {
                  "hosts": [
                    "<string>"
                  ]
                },
                "auth_data": {
                  "type": "basic",
                  "username": "<string>",
                  "password": "<string>"
                }
              }
            ]
          }
        },
        "dynamic_sub_agents": {
          "enabled": true
        },
        "context_management": {
          "compaction": {
            "enabled": true,
            "compaction_threshold_tokens": 50000
          },
          "large_tool_response": {
            "enabled": true
          }
        },
        "generative_ui": {
          "enabled": true
        },
        "ask_user_questions": {
          "enabled": true
        }
      },
      "collaborators": [
        {
          "subject": "<string>",
          "role_id": "<string>"
        }
      ],
      "ownedBy": {
        "account": "<string>"
      }
    },
    "version": 123,
    "id": "jqfwg345gi25n5ju2yz5iz6m",
    "metadata": {
      "promptVariables": {}
    },
    "createdBySubject": {
      "subjectId": "<string>",
      "subjectType": "user",
      "subjectSlug": "<string>",
      "subjectDisplayName": "<string>",
      "subjectPatName": "<string>",
      "subjectControllerName": "<string>",
      "subjectExternalIdentitySlug": "<string>"
    }
  }
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

manifest · AgentManifestV2 · object · required

Agent Manifest

Show child attributes

dryRun · boolean | null · default: false

Validate the manifest and collaborators without persisting or syncing to the gateway store

Response

200

application/json

Agent created or updated successfully

data · AgentVersion · object · required

Agent Version

Show child attributes