Agents

Functions for creating, reading, updating, running, and wiring up agents. Edits create a new draft version; the user confirms deploy in chat before changes go live.

Linking distinguishes workspace tools (org-owned tool_…, made with tool-create) from integrations (catalog connectors such as Outlook, Jira, Slack). Use agent-link-tool / agent-link-integration accordingly — never mix them.

---

agent-create

Create an agent with explicit fields. shortDescription is the card/summary text; systemPrompt holds the full behavior instructions. Placement uses the scoped folder when set, otherwise org root.

Input

Field	Type	Required	Description
name	string	Yes	Short snake_case identifier (letters, digits, underscores; spaces become _).
shortDescription	string	Yes	Brief summary for listings.
systemPrompt	string	Yes	Full system / task instructions.
agentGuidelines	string	No	Optional extra guidelines.
conversationStarters	array	No	Up to 2 starters, each \{ name, prompt \}.

Output

Field	Type	Description
agentId	string	Id of the new agent (agt_…).
versionId	string	Id of the created version.

---

agent-ask-create

Show multiple-choice follow-up questions in chat before calling agent-create — for example to confirm scope or options once integrations are connected. This presents questions; it does not create anything.

Input

Field	Type	Required	Description
intro	string	Yes	Short friendly line (e.g. confirming a connection worked).
questions	array	Yes	1–5 questions, each \{ id, prompt, options: [\{ id, label \}], allowCustom? \}.

Output

Field	Type	Description
presented	boolean	true when the questions were shown.
intro	string	The intro echoed back.
questions	array	The questions echoed back for rendering.

---

agent-read

Read one agent: core metadata, the current editable version, systemPrompt, agentGuidelines, conversation starters, linked tools / integrations / tables / workflows / knowledge bases, and schedules.

Input

Field	Type	Required	Description
agentId	string	Yes	Agent id (agt_…).

Output

Field	Type	Description
agent	object	Full payload: metadata, current version (id, description, systemPrompt, agentGuidelines, timestamps, deployed flag), conversationStarters[], linkedTools[], integrations[], linkedTables[], linkedWorkflows[], linkedKnowledgeBases[], schedules[].

---

agent-update

Update an existing agent (same fields as agent-create). Only include fields that should change; at least one is required. Commits a new draft version that the user must deploy.

Input

Field	Type	Required	Description
agentId	string	Yes	Agent id.
name	string	No	New snake_case name.
shortDescription	string	No	New summary.
systemPrompt	string	No	New system prompt.
agentGuidelines	string	No	New guidelines.
conversationStarters	array	No	When set, replaces all starters (max 2).

Output

Field	Type	Description
agentId	string	The agent id.
versionId	string	The committed draft version id.

---

agent-run

Execute an agent with a text input. The org, user, session, and call ids are set automatically. Requires the execution backend to be configured.

Input

Field	Type	Required	Description
agentId	string	Yes	Agent id.
input	string	Yes	Task or message for the agent.

Output

Field	Type	Description
agentId	string	The resolved agent id.
versionId	string	Version used for the run.
sessionId	string	Derived run session id.
agentCallId	string	Derived call id.
result	object	Raw response payload from the execution backend.

---

agent-link-tool

Attach workspace tools (llm_tool / template_tool / code_tool, ids tool_…) to an agent. Use names in refs or ids in toolIds. If a tool needs an integration that isn't configured, the call returns requiresIntegrationConfig.

Input

Field	Type	Required	Description
agentId	string	Yes	Agent id.
refs	string[]	No	Tool names (not ids), e.g. ["join-orgs"].
toolIds	string[]	No	Tool ids, e.g. ["tool_…"].

Output

Field	Type	Description
agentId	string	The agent id.
versionId	string	The draft version the tools were added to.
linkedTools	array	Linked tools with toolId, toolName, toolType, integrationName.

---

agent-unlink-tool

Remove a workspace tool (tool_…) from an agent.

Input

Field	Type	Required	Description
agentId	string	Yes	Agent id.
ref	string	Yes	Tool id or name to remove.

Output

Field	Type	Description
agentId	string	The agent id.
versionId	string	The draft version.

---

agent-link-integration

Attach integrations (catalog connectors — OAuth/configured services) to an agent. Use integration ids or catalog names/refs. Returns requiresIntegrationConfig with missingIntegrations if any are not yet configured.

Input

Field	Type	Required	Description
agentId	string	Yes	Agent id.
refs	string[]	Yes	Integration ids or names (at least one).

Output

Field	Type	Description
agentId	string	The agent id.
versionId	string	The draft version the integrations were added to.

---

agent-unlink-integration

Remove an integration (catalog connector) from an agent.

Input

Field	Type	Required	Description
agentId	string	Yes	Agent id.
ref	string	Yes	Integration id or name to remove.

Output

Field	Type	Description
agentId	string	The agent id.
versionId	string	The draft version.

---

agent-link (unified)

Combined linker. Set relationType to tool or integration. Prefer the dedicated agent-link-tool / agent-link-integration functions when possible; this exists for convenience and legacy input shapes. relationType: schedule is not supported here (use the schedule functions).

Input

Field	Type	Required	Description
agentId	string	Yes	Agent id.
relationType	enum	Yes*	tool or integration (inferred from toolIds/integrationIds if omitted).
refs	string[]	No	Names/ids depending on relationType.
toolIds	string[]	No	Tool ids (implies tool).
integrationIds	string[]	No	Integration ids (implies integration).

Output — same as the corresponding dedicated link function (linkedTools[] for tools; agentId + versionId for integrations).

---

agent-unlink (unified)

Combined unlinker. Set relationType to tool or integration; pass ref (or legacy toolId/integrationId). Mirrors agent-link.

Input

Field	Type	Required	Description
agentId	string	Yes	Agent id.
relationType	enum	Yes*	tool or integration (inferred from toolId/integrationId).
ref	string	Yes	The tool/integration id or name to remove.

Output

Field	Type	Description
agentId	string	The agent id.
versionId	string	The draft version.