feat(agents): Support agent description

.changeset/20260911065947-regenerate-sdk-from-openapi.md

@@ -0,0 +1,5 @@
+---
+"@truefoundry/trueforge-sdk": patch
+---
+
+Regenerate SDK from updated OpenAPI spec.

.changeset/agent-description-ui.md

@@ -0,0 +1,5 @@
+---
+"@truefoundry/trueforge-ui": patch
+---
+
+Round-trip agent description through save/load and show it in the library and agent details.

.changeset/agent-description.md

@@ -0,0 +1,5 @@
+---
+"@truefoundry/trueforge": patch
+---
+
+Persist top-level agent description and sync it to ServiceFoundry on create/update.

.github/fern/openapi/openapi.json

@@ -29,6 +29,11 @@
           "created_by_subject": {
             "$ref": "#/components/schemas/CreatedBySubject"
           },
+          "description": {
+            "maxLength": 1024,
+            "minLength": 1,
+            "type": "string"
+          },
           "id": {
             "description": "Immutable server-generated agent identifier.",
             "minLength": 1,
@@ -44,6 +49,7 @@
         "required": [
           "id",
           "name",
+          "description",
           "manifest",
           "created_by_subject"
         ],
@@ -982,6 +988,11 @@
       "CreateAgentRequest": {
         "additionalProperties": false,
         "properties": {
+          "description": {
+            "maxLength": 1024,
+            "minLength": 1,
+            "type": "string"
+          },
           "manifest": {
             "$ref": "#/components/schemas/AgentSpec"
           },
@@ -991,6 +1002,7 @@
         },
         "required": [
           "name",
+          "description",
           "manifest"
         ],
         "type": "object"
@@ -5330,6 +5342,11 @@
       "UpdateAgentRequest": {
         "additionalProperties": false,
         "properties": {
+          "description": {
+            "maxLength": 1024,
+            "minLength": 1,
+            "type": "string"
+          },
           "manifest": {
             "$ref": "#/components/schemas/AgentSpec"
           }
@@ -6370,7 +6387,7 @@
         "x-fern-sdk-method-name": "get"
       },
       "put": {
-        "description": "Replaces the manifest for an existing agent keyed by immutable `agent_id`.",
+        "description": "Update an existing agent by immutable id.",
         "parameters": [
           {
             "description": "Immutable agent identifier.",

docs/openapi.json

@@ -29,6 +29,11 @@
           "created_by_subject": {
             "$ref": "#/components/schemas/CreatedBySubject"
           },
+          "description": {
+            "maxLength": 1024,
+            "minLength": 1,
+            "type": "string"
+          },
           "id": {
             "description": "Immutable server-generated agent identifier.",
             "minLength": 1,
@@ -44,6 +49,7 @@
         "required": [
           "id",
           "name",
+          "description",
           "manifest",
           "created_by_subject"
         ],
@@ -982,6 +988,11 @@
       "CreateAgentRequest": {
         "additionalProperties": false,
         "properties": {
+          "description": {
+            "maxLength": 1024,
+            "minLength": 1,
+            "type": "string"
+          },
           "manifest": {
             "$ref": "#/components/schemas/AgentSpec"
           },
@@ -991,6 +1002,7 @@
         },
         "required": [
           "name",
+          "description",
           "manifest"
         ],
         "type": "object"
@@ -5330,6 +5342,11 @@
       "UpdateAgentRequest": {
         "additionalProperties": false,
         "properties": {
+          "description": {
+            "maxLength": 1024,
+            "minLength": 1,
+            "type": "string"
+          },
           "manifest": {
             "$ref": "#/components/schemas/AgentSpec"
           }
@@ -6370,7 +6387,7 @@
         "x-fern-sdk-method-name": "get"
       },
       "put": {
-        "description": "Replaces the manifest for an existing agent keyed by immutable `agent_id`.",
+        "description": "Update an existing agent by immutable id.",
         "parameters": [
           {
             "description": "Immutable agent identifier.",

packages/frontend/package.json

@@ -26,7 +26,7 @@
     "@assistant-ui/core": "0.2.22",
     "@assistant-ui/react": "0.14.27",
     "@assistant-ui/store": "0.2.21",
-    "@truefoundry/assistant-ui-runtime": "0.1.36",
+    "@truefoundry/assistant-ui-runtime": "0.1.37",
     "@truefoundry/trueforge-sdk": "workspace:*",
     "@truefoundry/trueforge-ui": "workspace:*",
     "monaco-editor": "^0.52.0",

packages/trueforge-sdk/reference.md

@@ -158,6 +158,7 @@ Creates an agent and allocates an immutable id. Fails if `name` is already taken
 
 ```typescript
 await client.agents.create({
+    description: "description",
     manifest: {
         model: {
             name: "name"
@@ -275,7 +276,7 @@ await client.agents.get("agent_id");
 <dl>
 <dd>
 
-Replaces the manifest for an existing agent keyed by immutable `agent_id`.
+Update an existing agent by immutable id.
 </dd>
 </dl>
 </dd>

packages/trueforge-sdk/src/api/resources/agents/client/Client.ts

@@ -151,6 +151,7 @@ export class AgentsClient {
      *
      * @example
      *     await client.agents.create({
+     *         description: "description",
      *         manifest: {
      *             model: {
      *                 name: "name"
@@ -346,7 +347,7 @@ export class AgentsClient {
     }
 
     /**
-     * Replaces the manifest for an existing agent keyed by immutable `agent_id`.
+     * Update an existing agent by immutable id.
      *
      * @param {string} agent_id - Immutable agent identifier.
      * @param {TrueForge.UpdateAgentRequest} request

packages/trueforge-sdk/src/api/resources/agents/client/requests/CreateAgentRequest.ts

@@ -5,6 +5,7 @@ import type * as TrueForge from "../../../../index.js";
 /**
  * @example
  *     {
+ *         description: "description",
  *         manifest: {
  *             model: {
  *                 name: "name"
@@ -14,6 +15,7 @@ import type * as TrueForge from "../../../../index.js";
  *     }
  */
 export interface CreateAgentRequest {
+    description: string;
     manifest: TrueForge.AgentSpec;
     name: TrueForge.ResourceName;
 }

packages/trueforge-sdk/src/api/resources/agents/client/requests/UpdateAgentRequest.ts

@@ -13,5 +13,6 @@ import type * as TrueForge from "../../../../index.js";
  *     }
  */
 export interface UpdateAgentRequest {
+    description?: string;
     manifest: TrueForge.AgentSpec;
 }

packages/trueforge-sdk/src/api/types/Agent.ts

@@ -4,6 +4,7 @@ import type * as TrueForge from "../index.js";
 
 export interface Agent {
     createdBySubject: TrueForge.CreatedBySubject;
+    description: string;
     /** Immutable server-generated agent identifier. */
     id: string;
     manifest: TrueForge.AgentSpec;

packages/trueforge-sdk/src/serialization/resources/agents/client/requests/CreateAgentRequest.ts

@@ -10,12 +10,14 @@ export const CreateAgentRequest: core.serialization.Schema<
     serializers.CreateAgentRequest.Raw,
     TrueForge.CreateAgentRequest
 > = core.serialization.object({
+    description: core.serialization.string(),
     manifest: AgentSpec,
     name: ResourceName,
 });
 
 export declare namespace CreateAgentRequest {
     export interface Raw {
+        description: string;
         manifest: AgentSpec.Raw;
         name: ResourceName.Raw;
     }

packages/trueforge-sdk/src/serialization/resources/agents/client/requests/UpdateAgentRequest.ts

@@ -9,11 +9,13 @@ export const UpdateAgentRequest: core.serialization.Schema<
     serializers.UpdateAgentRequest.Raw,
     TrueForge.UpdateAgentRequest
 > = core.serialization.object({
+    description: core.serialization.string().optional(),
     manifest: AgentSpec,
 });
 
 export declare namespace UpdateAgentRequest {
     export interface Raw {
+        description?: string | null;
         manifest: AgentSpec.Raw;
     }
 }

packages/trueforge-sdk/src/serialization/types/Agent.ts

@@ -10,6 +10,7 @@ import { ResourceName } from "./ResourceName.js";
 export const Agent: core.serialization.ObjectSchema<serializers.Agent.Raw, TrueForge.Agent> = core.serialization.object(
     {
         createdBySubject: core.serialization.property("created_by_subject", CreatedBySubject),
+        description: core.serialization.string(),
         id: core.serialization.string(),
         manifest: AgentSpec,
         name: ResourceName,
@@ -19,6 +20,7 @@ export const Agent: core.serialization.ObjectSchema<serializers.Agent.Raw, TrueF
 export declare namespace Agent {
     export interface Raw {
         created_by_subject: CreatedBySubject.Raw;
+        description: string;
         id: string;
         manifest: AgentSpec.Raw;
         name: ResourceName.Raw;

packages/trueforge-sdk/tests/wire/agents.test.ts

@@ -17,6 +17,7 @@ describe("AgentsClient", () => {
                         subject_id: "subject_id",
                         subject_type: "subject_type",
                     },
+                    description: "description",
                     id: "id",
                     manifest: { model: { name: "name" } },
                     name: "name",
@@ -41,6 +42,7 @@ describe("AgentsClient", () => {
                         subjectId: "subject_id",
                         subjectType: "subject_type",
                     },
+                    description: "description",
                     id: "id",
                     manifest: {
                         model: {
@@ -93,14 +95,15 @@ describe("AgentsClient", () => {
     test("create (1)", async () => {
         const server = mockServerPool.createServer();
         const client = new TrueForge({ maxRetries: 0, token: "test", baseUrl: server.baseUrl });
-        const rawRequestBody = { manifest: { model: { name: "name" } }, name: "name" };
+        const rawRequestBody = { description: "description", manifest: { model: { name: "name" } }, name: "name" };
         const rawResponseBody = {
             data: {
                 created_by_subject: {
                     subject_display_name: "subject_display_name",
                     subject_id: "subject_id",
                     subject_type: "subject_type",
                 },
+                description: "description",
                 id: "id",
                 manifest: {
                     instructions: "instructions",
@@ -124,6 +127,7 @@ describe("AgentsClient", () => {
             .build();
 
         const response = await client.agents.create({
+            description: "description",
             manifest: {
                 model: {
                     name: "name",
@@ -138,6 +142,7 @@ describe("AgentsClient", () => {
                     subjectId: "subject_id",
                     subjectType: "subject_type",
                 },
+                description: "description",
                 id: "id",
                 manifest: {
                     instructions: "instructions",
@@ -172,7 +177,7 @@ describe("AgentsClient", () => {
     test("create (2)", async () => {
         const server = mockServerPool.createServer();
         const client = new TrueForge({ maxRetries: 0, token: "test", baseUrl: server.baseUrl });
-        const rawRequestBody = { manifest: { model: { name: "x" } }, name: "xy" };
+        const rawRequestBody = { description: "x", manifest: { model: { name: "x" } }, name: "xy" };
         const rawResponseBody = { error: { message: "message" } };
 
         server
@@ -186,6 +191,7 @@ describe("AgentsClient", () => {
 
         await expect(async () => {
             return await client.agents.create({
+                description: "x",
                 manifest: {
                     model: {
                         name: "x",
@@ -199,7 +205,7 @@ describe("AgentsClient", () => {
     test("create (3)", async () => {
         const server = mockServerPool.createServer();
         const client = new TrueForge({ maxRetries: 0, token: "test", baseUrl: server.baseUrl });
-        const rawRequestBody = { manifest: { model: { name: "x" } }, name: "xy" };
+        const rawRequestBody = { description: "x", manifest: { model: { name: "x" } }, name: "xy" };
         const rawResponseBody = { error: { message: "message" } };
 
         server
@@ -213,6 +219,7 @@ describe("AgentsClient", () => {
 
         await expect(async () => {
             return await client.agents.create({
+                description: "x",
                 manifest: {
                     model: {
                         name: "x",
@@ -226,7 +233,7 @@ describe("AgentsClient", () => {
     test("create (4)", async () => {
         const server = mockServerPool.createServer();
         const client = new TrueForge({ maxRetries: 0, token: "test", baseUrl: server.baseUrl });
-        const rawRequestBody = { manifest: { model: { name: "x" } }, name: "xy" };
+        const rawRequestBody = { description: "x", manifest: { model: { name: "x" } }, name: "xy" };
         const rawResponseBody = { error: { message: "message" } };
 
         server
@@ -240,6 +247,7 @@ describe("AgentsClient", () => {
 
         await expect(async () => {
             return await client.agents.create({
+                description: "x",
                 manifest: {
                     model: {
                         name: "x",
@@ -261,6 +269,7 @@ describe("AgentsClient", () => {
                     subject_id: "subject_id",
                     subject_type: "subject_type",
                 },
+                description: "description",
                 id: "id",
                 manifest: {
                     instructions: "instructions",
@@ -290,6 +299,7 @@ describe("AgentsClient", () => {
                     subjectId: "subject_id",
                     subjectType: "subject_type",
                 },
+                description: "description",
                 id: "id",
                 manifest: {
                     instructions: "instructions",
@@ -351,6 +361,7 @@ describe("AgentsClient", () => {
                     subject_id: "subject_id",
                     subject_type: "subject_type",
                 },
+                description: "description",
                 id: "id",
                 manifest: {
                     instructions: "instructions",
@@ -387,6 +398,7 @@ describe("AgentsClient", () => {
                     subjectId: "subject_id",
                     subjectType: "subject_type",
                 },
+                description: "description",
                 id: "id",
                 manifest: {
                     instructions: "instructions",

packages/trueforge-ui/package.json

@@ -95,7 +95,7 @@
     "@openuidev/react-headless": "^0.9.4",
     "@openuidev/react-lang": "^0.2.9",
     "@openuidev/react-ui": "^0.13.2",
-    "@truefoundry/assistant-ui-runtime": "0.1.36",
+    "@truefoundry/assistant-ui-runtime": "0.1.37",
     "@truefoundry/trueforge-sdk": "workspace:*",
     "chart.js": "^4.5.1",
     "clsx": "^2.1.1",