Skip to main content
POST
Commit a new version of an LLM agent with the given tools

Authorizations

Authorization
string
header
required

API key: key id as the username, secret as the password. An account API key carries the same scopes as an OAuth token and is checked against the scopes listed under oauth2 on each operation. A trigger API key is limited to its trigger's workspace and reaches only the session operations that list this scheme alongside the oauth2 scopes.

Path Parameters

agent_id_or_name
string
required

Body

application/json
system_prompt
string
required

How the agent should behave

description
string
required

What the agent does, shown to people choosing an agent

tools
ConfigureLlmIntegrationToolsInput · object[]
required

Integration tools the agent may call, e.g. [{"integration": "github", "tools": ["github_issues_get"]}]

guild_tools
string[]

Built-in Guild tools the agent may call, e.g. ["guild_search_agent"]

mode
enum<string>
default:one-shot

One-shot answers once; multi-turn keeps a conversation (default one-shot)

Available options:
one-shot,
multi-turn
summary
string | null

What changed

version_number
string
default:1.0.0

Response

The newly committed agent version

job_id
string<uuid> | null
required

The validation or publish job this request started; null when it started none.

id
string<uuid>
created_at
string<date-time>
updated_at
string<date-time>
agent_id
string<uuid>
author_id
string<uuid>
validation_status
enum<string>
Available options:
SKIPPED,
PENDING,
RUNNING,
PASSED,
FAILED
dependencies
object | null

npm package.json dependencies

description
string | null

Description for the agent extracted from the agent code.

Maximum string length: 8192
env_references
any[] | null

Workspace variable keys referenced as {{env.KEY}} in the version's prompt, extracted at build time

input_schema
object | null

JSON Schema from Zod input

llm_models
any[] | null

Acceptable provider/model pairs from guild.yaml models, tried in order. An entry naming a model asks for exactly it; an entry naming only a provider lets the server pick. NULL means the agent declared none and runs on the session default. E.g. [{"provider": "ANTHROPIC", "model": "claude-sonnet-5"}, {"provider": "OPENAI"}]

output_schema
object | null

JSON Schema from Zod output

published_at
string<date-time> | null
publishing_started_at
string<date-time> | null
raw_tools
any[] | null

Structured per-tool metadata. Each entry is a tool object discriminated by toolType (integration, legacy, agent, builtin).

runtime_environment_id
string<uuid> | null
sha
string | null

Git commit SHA (40-character hexadecimal). For agents: set on version creation. For integrations: set after code is stored in GitHub.

Maximum string length: 40
summary
string | null

Commit message summary. For agents: set on version creation. For integrations: set after code is stored in GitHub.

Maximum string length: 500
tools
any[] | null
version_number
string | null

The semantic version number (i.e., MAJOR.MINOR.PATCH) of this version

Maximum string length: 100
agent
any
author
any
status
any
version_type
any