Skip to content

The open-source agent harness - the runtime layer that turns an LLM into a working agent.

Propagate truefoundry managed agent id in internal import (#726)

Chirag Jain93793574e4a9
diff --git a/.changeset/pre/tfy-import-collaborators.md b/.changeset/pre/tfy-import-collaborators.md
index ab327e238..338ff79ee 100644
--- a/.changeset/pre/tfy-import-collaborators.md
+++ b/.changeset/pre/tfy-import-collaborators.md
@@ -2,4 +2,4 @@
"@truefoundry/trueforge": patch
---
-Pass collaborators through TrueFoundry agent import.
+Pass TrueFoundry agents metadata through TrueFoundry agent import.
diff --git a/.github/fern/openapi/openapi.json b/.github/fern/openapi/openapi.json
index 0a15995a4..3e3ad2baf 100644
--- a/.github/fern/openapi/openapi.json
+++ b/.github/fern/openapi/openapi.json
@@ -1701,20 +1701,9 @@
],
"type": "object"
},
- "ImportAgentCollaborator": {
- "additionalProperties": {},
- "properties": {},
- "type": "object"
- },
"ImportAgentItem": {
"additionalProperties": false,
"properties": {
- "collaborators": {
- "items": {
- "$ref": "#/components/schemas/ImportAgentCollaborator"
- },
- "type": "array"
- },
"created_by_subject": {
"allOf": [
{
@@ -1740,13 +1729,17 @@
"description": "Tenant to create the agent under.",
"minLength": 1,
"type": "string"
+ },
+ "truefoundry_managed_agent_id": {
+ "type": "string"
}
},
"required": [
"name",
"manifest",
"tenant_id",
- "created_by_subject"
+ "created_by_subject",
+ "truefoundry_managed_agent_id"
],
"type": "object"
},
@@ -5653,7 +5646,7 @@
"info": {
"description": "HTTP API for the TrueForge agent server (`/api/v1`). Interactive docs are served at `/api/v1/docs` (OpenAPI JSON at `/api/v1/openapi.json`).\n\n**Authentication:** Standalone auth accepts requests without credentials — middleware stamps a local default user. When OIDC or TrueFoundry auth is configured, protected routes require a valid cookie or `Authorization: Bearer` token. There is no built-in API-key scheme; pass custom headers only if your reverse proxy or IdP layer requires them.\n\nCovers DB-backed sessions, the agent registry, settings catalogs, and model/MCP/skill/sandbox providers.",
"title": "TrueForge API",
- "version": "0.2.0-rc.6"
+ "version": "0.2.0-rc.7"
},
"openapi": "3.1.0",
"paths": {
diff --git a/docs/openapi.json b/docs/openapi.json
index 0a15995a4..3e3ad2baf 100644
--- a/docs/openapi.json
+++ b/docs/openapi.json
@@ -1701,20 +1701,9 @@
],
"type": "object"
},
- "ImportAgentCollaborator": {
- "additionalProperties": {},
- "properties": {},
- "type": "object"
- },
"ImportAgentItem": {
"additionalProperties": false,
"properties": {
- "collaborators": {
- "items": {
- "$ref": "#/components/schemas/ImportAgentCollaborator"
- },
- "type": "array"
- },
"created_by_subject": {
"allOf": [
{
@@ -1740,13 +1729,17 @@
"description": "Tenant to create the agent under.",
"minLength": 1,
"type": "string"
+ },
+ "truefoundry_managed_agent_id": {
+ "type": "string"
}
},
"required": [
"name",
"manifest",
"tenant_id",
- "created_by_subject"
+ "created_by_subject",
+ "truefoundry_managed_agent_id"
],
"type": "object"
},
@@ -5653,7 +5646,7 @@
"info": {
"description": "HTTP API for the TrueForge agent server (`/api/v1`). Interactive docs are served at `/api/v1/docs` (OpenAPI JSON at `/api/v1/openapi.json`).\n\n**Authentication:** Standalone auth accepts requests without credentials — middleware stamps a local default user. When OIDC or TrueFoundry auth is configured, protected routes require a valid cookie or `Authorization: Bearer` token. There is no built-in API-key scheme; pass custom headers only if your reverse proxy or IdP layer requires them.\n\nCovers DB-backed sessions, the agent registry, settings catalogs, and model/MCP/skill/sandbox providers.",
"title": "TrueForge API",
- "version": "0.2.0-rc.6"
+ "version": "0.2.0-rc.7"
},
"openapi": "3.1.0",
"paths": {
diff --git a/packages/trueforge/src/apis/agentImport.ts b/packages/trueforge/src/apis/agentImport.ts
index 61816936d..8f5c56ded 100644
--- a/packages/trueforge/src/apis/agentImport.ts
+++ b/packages/trueforge/src/apis/agentImport.ts
@@ -51,7 +51,7 @@ export function createAgentImportRouter(deps: AgentImportRouterDeps) {
external_id: null,
created_by_subject: agent.created_by_subject,
custom: {
- ...(agent.collaborators ? { collaborators: agent.collaborators } : {}),
+ trueFoundryManagedAgentId: agent.truefoundry_managed_agent_id,
},
});
results.push({
diff --git a/packages/trueforge/src/schemas/agentImport.ts b/packages/trueforge/src/schemas/agentImport.ts
index 61f563ad1..3e05086f4 100644
--- a/packages/trueforge/src/schemas/agentImport.ts
+++ b/packages/trueforge/src/schemas/agentImport.ts
@@ -8,9 +8,6 @@ import { NameSchema } from './common';
const RESERVED_AGENT_NAMES = new Set(['tfg', 'trueforge']);
-/** Opaque collaborator grant forwarded to ServiceFoundry on import. */
-export const ImportAgentCollaboratorSchema = z.object({}).loose().openapi('ImportAgentCollaborator');
-
/** One import row: same fields as create-agent, plus explicit tenant and creator. */
export const ImportAgentItemSchema = z
.object({
@@ -21,7 +18,7 @@ export const ImportAgentItemSchema = z
manifest: AgentSpecSchema,
tenant_id: z.string().min(1).describe('Tenant to create the agent under.'),
created_by_subject: CreatedBySubjectSchema.describe('Original creator to persist on the agent.'),
- collaborators: z.array(ImportAgentCollaboratorSchema).optional(),
+ truefoundry_managed_agent_id: z.string(),
})
.strict()
.openapi('ImportAgentItem');
diff --git a/packages/trueforge/src/truefoundry/TrueFoundryAgentStore.ts b/packages/trueforge/src/truefoundry/TrueFoundryAgentStore.ts
index 73c163847..2b96df378 100644
--- a/packages/trueforge/src/truefoundry/TrueFoundryAgentStore.ts
+++ b/packages/trueforge/src/truefoundry/TrueFoundryAgentStore.ts
@@ -30,19 +30,19 @@ function toPutRemoteAgentPayload({
name,
description,
manifest,
- collaborators,
+ trueFoundryManagedAgentId,
}: {
name: string;
description: string;
manifest: AgentSpec;
- collaborators?: Record<string, unknown>[];
+ trueFoundryManagedAgentId?: string;
}): Omit<PutRemoteAgentInput, 'accessToken'> {
return {
name,
description: (description || name).slice(0, AGENT_DESCRIPTION_MAX_LENGTH),
model: manifest.model.name,
mcp_servers: (manifest.mcp_servers ?? []).map(server => server.name),
- ...(collaborators ? { collaborators } : {}),
+ ...(trueFoundryManagedAgentId ? { trueFoundryManagedAgentId } : {}),
};
}
@@ -138,14 +138,14 @@ export class TrueFoundryAgentStore implements IAgentStore<Transaction<Database>>
let externalId: string | undefined;
try {
- const collaborators = input.custom?.['collaborators'] as Record<string, unknown>[] | undefined;
+ const trueFoundryManagedAgentId = input.custom?.['trueFoundryManagedAgentId'] as string | undefined;
({ externalId } = await this.#client.putRemoteAgent({
accessToken: await this.#resolveAccessToken(),
...toPutRemoteAgentPayload({
name: input.name,
description: input.description,
manifest: input.manifest,
- ...(collaborators ? { collaborators } : {}),
+ ...(trueFoundryManagedAgentId ? { trueFoundryManagedAgentId } : {}),
}),
}));
const updated = await this.#inner.updateAgent(
diff --git a/packages/trueforge/src/truefoundry/TrueFoundryServiceFoundryServerClient.ts b/packages/trueforge/src/truefoundry/TrueFoundryServiceFoundryServerClient.ts
index b5fdf72e1..fd28adfd4 100644
--- a/packages/trueforge/src/truefoundry/TrueFoundryServiceFoundryServerClient.ts
+++ b/packages/trueforge/src/truefoundry/TrueFoundryServiceFoundryServerClient.ts
@@ -97,7 +97,7 @@ export interface PutRemoteAgentInput {
description: string;
model: string;
mcp_servers: string[];
- collaborators?: Record<string, unknown>[];
+ trueFoundryManagedAgentId?: string;
}
export interface PutRemoteAgentResult {
@@ -246,7 +246,7 @@ export class TrueFoundryServiceFoundryServerClient {
/** PUT `/internal/tfg/agents` — create/reuse remote agent + sync model/MCP grants. */
async putRemoteAgent(input: PutRemoteAgentInput): Promise<PutRemoteAgentResult> {
- const hasCollaborators = input.collaborators && input.collaborators.length > 0;
+ const hasTrueFoundryManagedAgentId = input.trueFoundryManagedAgentId !== undefined;
const payload = await this.#requestJson({
url: this.#url(TFG_AGENTS_PATH),
accessToken: input.accessToken,
@@ -257,7 +257,7 @@ export class TrueFoundryServiceFoundryServerClient {
description: input.description,
model: input.model,
mcp_servers: input.mcp_servers,
- ...(hasCollaborators ? { collaborators: input.collaborators } : {}),
+ ...(hasTrueFoundryManagedAgentId ? { trueFoundryManagedAgentId: input.trueFoundryManagedAgentId } : {}),
},
});
const parsed = PutRemoteAgentResponseSchema.safeParse(payload);
diff --git a/packages/trueforge/tests/unit/truefoundry/TrueFoundryAgentStore.test.ts b/packages/trueforge/tests/unit/truefoundry/TrueFoundryAgentStore.test.ts
index e34047494..9d66285fe 100644
--- a/packages/trueforge/tests/unit/truefoundry/TrueFoundryAgentStore.test.ts
+++ b/packages/trueforge/tests/unit/truefoundry/TrueFoundryAgentStore.test.ts
@@ -204,44 +204,6 @@ describe('TrueFoundryAgentStore', () => {
expect(firstInvocationOrder(putRemoteAgent)).toBeLessThan(firstInvocationOrder(updateAgent));
});
- it('createAgent forwards collaborators from custom into putRemoteAgent', async () => {
- const collaborators = [{ subject: 'user:[email protected]', role_id: 'agent-manager' }];
- const local = record({ external_id: null });
- const linked = record({ external_id: 'sf-1' });
- const putRemoteAgent = jest.fn(async (input: PutRemoteAgentInput) => {
- expect(input.collaborators).toEqual(collaborators);
- return { externalId: 'sf-1' };
- });
- const store = tfStore({
- inner: mockInner({
- createAgent: jest.fn(async () => local),
- updateAgent: jest.fn(async () => linked),
- }),
- client: mockClient({ putRemoteAgent }),
- });
-
- await expect(
- store.createAgent(
- {
- tenant_id: TENANT,
- created_by_subject: CREATED_BY_SUBJECT,
- name: 'research',
- description: 'research',
- manifest: manifest(),
- external_id: null,
- custom: { collaborators },
- },
- TXN,
- ),
- ).resolves.toBe(linked);
- expect(putRemoteAgent).toHaveBeenCalledWith(
- expect.objectContaining({
- name: 'research',
- collaborators,
- }),
- );
- });
-
it('createAgent rejects a duplicate local name before calling ServiceFoundry', async () => {
const createAgent = jest.fn(async () => {
throw new AgentNameConflictError({ tenant_id: TENANT, name: 'research' });