Skip to content

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

feat: add Python samples to agent Use in Code (#736)

Bhavesh Patel9846d6d9a144
diff --git a/.changeset/20260914190823-regenerate-sdk-from-openapi.md b/.changeset/20260914190823-regenerate-sdk-from-openapi.md
new file mode 100644
index 000000000..efd8ff00f
--- /dev/null
+++ b/.changeset/20260914190823-regenerate-sdk-from-openapi.md
@@ -0,0 +1,5 @@
+---
+"@truefoundry/trueforge-sdk": patch
+---
+
+Regenerate SDK from updated OpenAPI spec.
diff --git a/.changeset/python-use-in-code-snippets.md b/.changeset/python-use-in-code-snippets.md
new file mode 100644
index 000000000..ef096572e
--- /dev/null
+++ b/.changeset/python-use-in-code-snippets.md
@@ -0,0 +1,5 @@
+---
+"@truefoundry/trueforge": patch
+---
+
+Add Python TrueForge SDK stream and non-stream samples to agent Use in Code snippets.
diff --git a/.github/fern/openapi/openapi.json b/.github/fern/openapi/openapi.json
index e53a777df..1de76d761 100644
--- a/.github/fern/openapi/openapi.json
+++ b/.github/fern/openapi/openapi.json
@@ -6522,7 +6522,7 @@
},
"/api/v1/agents/{agent_id}/code-snippets": {
"get": {
- "description": "TypeScript TrueForge SDK samples (stream and non-stream) for creating a session and turn against this agent.",
+ "description": "TrueForge SDK samples (TypeScript and Python, stream and non-stream) for a session and turn against this agent.",
"parameters": [
{
"description": "Immutable agent identifier.",
@@ -6557,7 +6557,7 @@
}
}
},
- "description": "TypeScript SDK samples."
+ "description": "SDK samples."
},
"404": {
"content": {
diff --git a/docs/openapi.json b/docs/openapi.json
index e53a777df..1de76d761 100644
--- a/docs/openapi.json
+++ b/docs/openapi.json
@@ -6522,7 +6522,7 @@
},
"/api/v1/agents/{agent_id}/code-snippets": {
"get": {
- "description": "TypeScript TrueForge SDK samples (stream and non-stream) for creating a session and turn against this agent.",
+ "description": "TrueForge SDK samples (TypeScript and Python, stream and non-stream) for a session and turn against this agent.",
"parameters": [
{
"description": "Immutable agent identifier.",
@@ -6557,7 +6557,7 @@
}
}
},
- "description": "TypeScript SDK samples."
+ "description": "SDK samples."
},
"404": {
"content": {
diff --git a/packages/trueforge-sdk/reference.md b/packages/trueforge-sdk/reference.md
index 01146ce9b..a831a70fe 100644
--- a/packages/trueforge-sdk/reference.md
+++ b/packages/trueforge-sdk/reference.md
@@ -3136,7 +3136,7 @@ await client.internal.sessions.getOrCreateByExternalId({
<dl>
<dd>
-TypeScript TrueForge SDK samples (stream and non-stream) for creating a session and turn against this agent.
+TrueForge SDK samples (TypeScript and Python, stream and non-stream) for a session and turn against this agent.
</dd>
</dl>
</dd>
diff --git a/packages/trueforge-sdk/src/api/resources/internal/resources/agents/client/Client.ts b/packages/trueforge-sdk/src/api/resources/internal/resources/agents/client/Client.ts
index b3168d890..b9a69f038 100644
--- a/packages/trueforge-sdk/src/api/resources/internal/resources/agents/client/Client.ts
+++ b/packages/trueforge-sdk/src/api/resources/internal/resources/agents/client/Client.ts
@@ -23,7 +23,7 @@ export class AgentsClient {
}
/**
- * TypeScript TrueForge SDK samples (stream and non-stream) for creating a session and turn against this agent.
+ * TrueForge SDK samples (TypeScript and Python, stream and non-stream) for a session and turn against this agent.
*
* @param {string} agent_id - Immutable agent identifier.
* @param {TrueForge.internal.GetCodeSnippetsAgentsRequest} request
diff --git a/packages/trueforge/src/apis/agentCodeSnippets.ts b/packages/trueforge/src/apis/agentCodeSnippets.ts
index eabc9ab1c..108173b8c 100644
--- a/packages/trueforge/src/apis/agentCodeSnippets.ts
+++ b/packages/trueforge/src/apis/agentCodeSnippets.ts
@@ -1,20 +1,19 @@
import { getTrueForgeAuthMode, TrueForgeAuthMode } from '../config';
import type { AgentCodeSnippets } from '../schemas/agent';
+import { pythonNonStreamTemplate, pythonStreamTemplate } from './codesnippet-templates/python';
import { typescriptNonStreamTemplate, typescriptStreamTemplate } from './codesnippet-templates/typescript';
const TYPESCRIPT_ICON = 'https://assets.production.truefoundry.com/typescript.svg';
-
-/** Bearer `token` for OIDC / TrueFoundry; omitted in standalone where login is off. */
-const TOKEN_LINE = '\n token: "USER_API_KEY",';
+const PYTHON_ICON = 'https://assets.production.truefoundry.com/python.svg';
function renderSnippetTemplate(
template: string,
- vars: { agentName: string; baseUrl: string; includeToken: boolean },
+ vars: { agentName: string; baseUrl: string; tokenLine: string },
): string {
const literals: Record<string, string> = {
agentName: JSON.stringify(vars.agentName),
baseUrl: JSON.stringify(vars.baseUrl),
- tokenLine: vars.includeToken ? TOKEN_LINE : '',
+ tokenLine: vars.tokenLine,
};
return template.replaceAll(/\{\{(\w+)\}\}/g, (match, key: string) => {
const value = literals[key];
@@ -27,7 +26,16 @@ function renderSnippetTemplate(
export function buildAgentCodeSnippets(input: { agentName: string; baseUrl: string }): AgentCodeSnippets {
const includeToken = getTrueForgeAuthMode() !== TrueForgeAuthMode.Standalone;
- const vars = { ...input, includeToken };
+ const tsVars = {
+ agentName: input.agentName,
+ baseUrl: input.baseUrl,
+ tokenLine: includeToken ? '\n token: "USER_API_KEY",' : '',
+ };
+ // Python kwarg (`token=`) vs TS object field (`token:`), including indent.
+ const pyVars = {
+ ...tsVars,
+ tokenLine: includeToken ? '\n token="USER_API_KEY",' : '',
+ };
return {
base_url: input.baseUrl,
snippets: [
@@ -36,8 +44,17 @@ export function buildAgentCodeSnippets(input: { agentName: string; baseUrl: stri
language: 'typescript',
icon: TYPESCRIPT_ICON,
sample_code: {
- stream: renderSnippetTemplate(typescriptStreamTemplate, vars),
- non_stream: renderSnippetTemplate(typescriptNonStreamTemplate, vars),
+ stream: renderSnippetTemplate(typescriptStreamTemplate, tsVars),
+ non_stream: renderSnippetTemplate(typescriptNonStreamTemplate, tsVars),
+ },
+ },
+ {
+ label_name: 'Python',
+ language: 'python',
+ icon: PYTHON_ICON,
+ sample_code: {
+ stream: renderSnippetTemplate(pythonStreamTemplate, pyVars),
+ non_stream: renderSnippetTemplate(pythonNonStreamTemplate, pyVars),
},
},
],
diff --git a/packages/trueforge/src/apis/codesnippet-templates/python.ts b/packages/trueforge/src/apis/codesnippet-templates/python.ts
new file mode 100644
index 000000000..56cc8bba8
--- /dev/null
+++ b/packages/trueforge/src/apis/codesnippet-templates/python.ts
@@ -0,0 +1,42 @@
+export const pythonStreamTemplate = `# pip install trueforge-sdk
+from trueforge_sdk import TrueForge
+
+client = TrueForge(
+ base_url={{baseUrl}},{{tokenLine}}
+)
+
+session = client.sessions.create(
+ agent={"name": {{agentName}}},
+)
+
+stream = client.sessions.create_turn_stream(
+ session_id=session.data.id,
+ input=[{"type": "user.message", "content": "Hello!"}],
+)
+
+for event in stream:
+ print(event)
+`;
+
+export const pythonNonStreamTemplate = `# pip install trueforge-sdk
+from trueforge_sdk import TrueForge
+
+client = TrueForge(
+ base_url={{baseUrl}},{{tokenLine}}
+)
+
+session = client.sessions.create(
+ agent={"name": {{agentName}}},
+)
+
+turn = client.sessions.create_turn(
+ session_id=session.data.id,
+ input=[{"type": "user.message", "content": "Hello!"}],
+)
+
+print(turn.data.id, turn.data.state)
+
+# Call get_turn to check turn state.
+latest = client.sessions.get_turn(session_id=session.data.id, turn_id=turn.data.id)
+print(latest.data.state)
+`;
diff --git a/packages/trueforge/src/routes/agentRoutes.ts b/packages/trueforge/src/routes/agentRoutes.ts
index aa1e88db7..df0b89b28 100644
--- a/packages/trueforge/src/routes/agentRoutes.ts
+++ b/packages/trueforge/src/routes/agentRoutes.ts
@@ -106,7 +106,7 @@ export const getAgentCodeSnippetsRoute = createRoute({
tags: [OpenApiTag.AGENTS],
summary: 'Get agent SDK code snippets',
description:
- 'TypeScript TrueForge SDK samples (stream and non-stream) for creating a session and turn against this agent.',
+ 'TrueForge SDK samples (TypeScript and Python, stream and non-stream) for a session and turn against this agent.',
'x-fern-sdk-group-name': ['internal', 'agents'],
'x-fern-sdk-method-name': 'get_code_snippets',
'x-excluded': true,
@@ -117,7 +117,7 @@ export const getAgentCodeSnippetsRoute = createRoute({
responses: {
200: {
content: { 'application/json': { schema: GetAgentCodeSnippetsResponseSchema } },
- description: 'TypeScript SDK samples.',
+ description: 'SDK samples.',
},
404: {
content: { 'application/json': { schema: RequestErrorResponseSchema } },
diff --git a/packages/trueforge/tests/unit/apis/agents.test.ts b/packages/trueforge/tests/unit/apis/agents.test.ts
index 6b29d4c41..f6cea8495 100644
--- a/packages/trueforge/tests/unit/apis/agents.test.ts
+++ b/packages/trueforge/tests/unit/apis/agents.test.ts
@@ -195,7 +195,7 @@ describe('agents router', () => {
const body = (await response.json()) as {
data: {
base_url: string;
- snippets: Array<{ sample_code: { stream: string; non_stream: string } }>;
+ snippets: Array<{ language: string; sample_code: { stream: string; non_stream: string } }>;
};
};
expect(body.data.base_url).toBe(
@@ -203,9 +203,14 @@ describe('agents router', () => {
? new URL(new URL(configuration.PUBLIC_BASE_URL).pathname, 'http://localhost').href
: 'http://localhost',
);
- expect(body.data.snippets.length).toBeGreaterThan(0);
- expect(body.data.snippets[0]?.sample_code.stream).not.toContain('USER_API_KEY');
- expect(body.data.snippets[0]?.sample_code.non_stream).not.toContain('USER_API_KEY');
+ expect(body.data.snippets.map(snippet => snippet.language)).toEqual(['typescript', 'python']);
+ const python = body.data.snippets.find(snippet => snippet.language === 'python');
+ expect(python?.sample_code.stream).toContain('create_turn_stream');
+ expect(python?.sample_code.non_stream).toContain('create_turn');
+ for (const snippet of body.data.snippets) {
+ expect(snippet.sample_code.stream).not.toContain('USER_API_KEY');
+ expect(snippet.sample_code.non_stream).not.toContain('USER_API_KEY');
+ }
const overridden = await router.request(
`/${createdJson.data.id}/code-snippets?base_url=${encodeURIComponent('https://sample.com/trueforge')}`,
diff --git a/python/trueforge_sdk/.fern/metadata.json b/python/trueforge_sdk/.fern/metadata.json
index 8a2a38aee..00db8935f 100644
--- a/python/trueforge_sdk/.fern/metadata.json
+++ b/python/trueforge_sdk/.fern/metadata.json
@@ -21,8 +21,8 @@
},
"pyproject_python_version": ">=3.10"
},
- "originGitCommit": "811c4e0b456f592e6b6c763cdb34361291160228",
- "originGitCommitIsDirty": false,
+ "originGitCommit": "61381cac574f43a00441fd61302a1698b772ca56",
+ "originGitCommitIsDirty": true,
"invokedBy": "ci",
"requestedVersion": "0.2.0-rc.7",
"ciProvider": "github"
diff --git a/python/trueforge_sdk/reference.md b/python/trueforge_sdk/reference.md
index 0f8caedb6..352def7b7 100644
--- a/python/trueforge_sdk/reference.md
+++ b/python/trueforge_sdk/reference.md
@@ -3731,7 +3731,7 @@ client.internal.sessions.get_or_create_by_external_id(
<dl>
<dd>
-TypeScript TrueForge SDK samples (stream and non-stream) for creating a session and turn against this agent.
+TrueForge SDK samples (TypeScript and Python, stream and non-stream) for a session and turn against this agent.
</dd>
</dl>
</dd>
diff --git a/python/trueforge_sdk/src/trueforge_sdk/internal/agents/client.py b/python/trueforge_sdk/src/trueforge_sdk/internal/agents/client.py
index d9aed5f35..65d681688 100644
--- a/python/trueforge_sdk/src/trueforge_sdk/internal/agents/client.py
+++ b/python/trueforge_sdk/src/trueforge_sdk/internal/agents/client.py
@@ -31,7 +31,7 @@ class AgentsClient:
request_options: typing.Optional[RequestOptions] = None,
) -> GetAgentCodeSnippetsResponse:
"""
- TypeScript TrueForge SDK samples (stream and non-stream) for creating a session and turn against this agent.
+ TrueForge SDK samples (TypeScript and Python, stream and non-stream) for a session and turn against this agent.
Parameters
----------
@@ -47,7 +47,7 @@ class AgentsClient:
Returns
-------
GetAgentCodeSnippetsResponse
- TypeScript SDK samples.
+ SDK samples.
Examples
--------
@@ -90,7 +90,7 @@ class AsyncAgentsClient:
request_options: typing.Optional[RequestOptions] = None,
) -> GetAgentCodeSnippetsResponse:
"""
- TypeScript TrueForge SDK samples (stream and non-stream) for creating a session and turn against this agent.
+ TrueForge SDK samples (TypeScript and Python, stream and non-stream) for a session and turn against this agent.
Parameters
----------
@@ -106,7 +106,7 @@ class AsyncAgentsClient:
Returns
-------
GetAgentCodeSnippetsResponse
- TypeScript SDK samples.
+ SDK samples.
Examples
--------
diff --git a/python/trueforge_sdk/src/trueforge_sdk/internal/agents/raw_client.py b/python/trueforge_sdk/src/trueforge_sdk/internal/agents/raw_client.py
index 9dbfe6ca7..e6e351f51 100644
--- a/python/trueforge_sdk/src/trueforge_sdk/internal/agents/raw_client.py
+++ b/python/trueforge_sdk/src/trueforge_sdk/internal/agents/raw_client.py
@@ -28,7 +28,7 @@ class RawAgentsClient:
request_options: typing.Optional[RequestOptions] = None,
) -> HttpResponse[GetAgentCodeSnippetsResponse]:
"""
- TypeScript TrueForge SDK samples (stream and non-stream) for creating a session and turn against this agent.
+ TrueForge SDK samples (TypeScript and Python, stream and non-stream) for a session and turn against this agent.
Parameters
----------
@@ -44,7 +44,7 @@ class RawAgentsClient:
Returns
-------
HttpResponse[GetAgentCodeSnippetsResponse]
- TypeScript SDK samples.
+ SDK samples.
"""
_response = self._client_wrapper.httpx_client.request(
f"api/v1/agents/{encode_path_param(agent_id)}/code-snippets",
@@ -97,7 +97,7 @@ class AsyncRawAgentsClient:
request_options: typing.Optional[RequestOptions] = None,
) -> AsyncHttpResponse[GetAgentCodeSnippetsResponse]:
"""
- TypeScript TrueForge SDK samples (stream and non-stream) for creating a session and turn against this agent.
+ TrueForge SDK samples (TypeScript and Python, stream and non-stream) for a session and turn against this agent.
Parameters
----------
@@ -113,7 +113,7 @@ class AsyncRawAgentsClient:
Returns
-------
AsyncHttpResponse[GetAgentCodeSnippetsResponse]
- TypeScript SDK samples.
+ SDK samples.
"""
_response = await self._client_wrapper.httpx_client.request(
f"api/v1/agents/{encode_path_param(agent_id)}/code-snippets",