Pull agent definition (config-as-code)

GET

/v1/agents/pull

GET

/v1/agents/pull

$ curl -G https://api.runtype.com/v1/agents/pull \
>      -H "Authorization: <apiKey>" \
>      -H "Content-Type: application/json" \
>      -d name=name

1 {
2   "agentId": "agent_9f8b7c6d5e4a3b2c1d0e",
3   "contentHash": "3a7bd3e2360a3f5b9c8d7e6f4a1b2c3d",
4   "definition": {
5     "name": "SupportAgent",
6     "config": {
7       "advisor": {
8         "model": "gpt-4-advisor-v1",
9         "systemPrompt": "You are an expert AI assistant providing guidance on agent configuration."
10       },
11       "artifacts": {
12         "enabled": true,
13         "types": [
14           "markdown",
15           "component"
16         ]
17       },
18       "errorHandling": {
19         "onError": "fail",
20         "fallbacks": [
21           {
22             "delay": 5000,
23             "type": "retry"
24           }
25         ],
26         "triggers": [
27           {
28             "type": "error"
29           }
30         ]
31       },
32       "frequencyPenalty": 0.5,
33       "loggingPolicy": "default",
34       "loopConfig": {
35         "enableReflection": true,
36         "maxCost": 10,
37         "maxTurns": 10,
38         "reflectionInterval": 5
39       },
40       "maxTokens": 2048,
41       "memory": {
42         "enabled": true,
43         "injectSummary": true,
44         "profileTemplate": "User interaction summary template"
45       },
46       "model": "gpt-4",
47       "presencePenalty": 0.3,
48       "reasoning": {
49         "enabled": true,
50         "budgetTokens": 5000,
51         "includeThoughts": true,
52         "reasoningEffort": "medium",
53         "reasoningSummary": "auto",
54         "thinkingBudget": 8192
55       },
56       "seed": 42,
57       "systemPrompt": "You are a helpful assistant.",
58       "temperature": 0.7,
59       "temporal": {
60         "elapsedThresholdSeconds": 60,
61         "groundNow": true,
62         "injectElapsed": true,
63         "timezone": "America/New_York"
64       },
65       "tools": {
66         "approval": {
67           "require": [
68             "admin_approval"
69           ],
70           "choices": {
71             "alwaysAllow": false,
72             "alwaysDeny": false
73           },
74           "requestReason": true,
75           "timeout": 30
76         },
77         "codeModeConfig": {
78           "toolPool": [
79             "code-analyzer",
80             "syntax-checker"
81           ],
82           "description": "Configuration for code mode tools",
83           "timeoutMs": 30000
84         },
85         "maxToolCalls": 10,
86         "mcpServers": [
87           {
88             "id": "server-1234",
89             "url": "https://mcp.runtype.com/api",
90             "allowedTools": [
91               "search",
92               "database"
93             ],
94             "auth": {
95               "type": "api_key",
96               "headerName": "Authorization",
97               "password": "s3cr3tP@ssw0rd",
98               "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9",
99               "username": "agent_user"
100             },
101             "enabled": true,
102             "name": "Primary MCP Server",
103             "timeout": 15,
104             "transport": "streamable_http"
105           }
106         ],
107         "perToolLimits": {
108           "search": {
109             "maxCalls": 100,
110             "required": true
111           },
112           "database": {
113             "maxCalls": 50,
114             "required": false
115           }
116         },
117         "runtimeTools": [
118           {
119             "config": {
120               "maxRetries": 3,
121               "logLevel": "info"
122             },
123             "description": "Flow control tool for managing conversation state",
124             "name": "FlowController",
125             "parametersSchema": {
126               "maxRetries": {
127                 "type": "integer",
128                 "minimum": 1,
129                 "maximum": 5
130               },
131               "logLevel": {
132                 "type": "string",
133                 "enum": [
134                   "debug",
135                   "info",
136                   "warn",
137                   "error"
138                 ]
139               }
140             },
141             "toolType": "flow"
142           }
143         ],
144         "subagentConfig": {
145           "toolPool": [
146             "subagent-tool-1",
147             "subagent-tool-2"
148           ],
149           "allowNesting": true,
150           "defaultMaxTurns": 5,
151           "defaultModel": "gpt-3.5-turbo",
152           "defaultTimeoutMs": 15000,
153           "maxSpawnsPerRun": 3,
154           "maxTurnsLimit": 10
155         },
156         "toolCallStrategy": "auto",
157         "toolConfigs": {
158           "search": {
159             "endpoint": "https://search.api.runtype.com",
160             "apiKey": "search-api-key-123"
161           }
162         },
163         "toolIds": [
164           "tool-abc123",
165           "tool-def456"
166         ]
167       },
168       "topK": 50,
169       "topP": 0.9,
170       "voice": {
171         "elevenLabs": {
172           "modelId": "eleven-v1",
173           "similarity": 0.85,
174           "stability": 0.75,
175           "voiceId": "voice_1234"
176         },
177         "enabled": true,
178         "interruptionMode": "cancel",
179         "provider": "elevenLabs"
180       }
181     },
182     "description": "Agent for customer support automation",
183     "icon": "robot-face"
184   },
185   "lastModifiedSource": "dashboard",
186   "updatedAt": "2024-06-01T12:00:00Z",
187   "versionId": "v1.2.3",
188   "warnings": [
189     "Tool reference 'old-tool-xyz' could not be resolved; please update to a supported tool name."
190   ]
191 }

Return the canonical config-as-code definition and provenance for an agent by name — the absorb-drift direction of the ensure protocol. The contentHash is recomputed from the live agent state, so it is accurate even immediately after a dashboard edit.

Authentication

AuthorizationBearer

API key or Clerk session token

Query parameters

namestringRequired>=1 character

Response

Canonical definition + provenance

agentIdstring

contentHashstring

definitionobject

lastModifiedSourcestring or null

updatedAtstring or null

versionIdstring or null

warningslist of strings

Present only when a raw tool_… reference could not be emitted as a portable tool:<name> (the tool was deleted, or its name is shadowed by an older same-named tool). Those references are left as raw ids, which the ensure surface rejects; each warning explains how to fix it.

Errors

400

Bad Request Error

401

Unauthorized Error

403

Forbidden Error

404

Not Found Error

500

Internal Server Error