Tool sets

Import any tool set and spread it into your agent’s tools object. Each tool set is a plain object whose keys are tool names — you can spread multiple sets together, or use pick / omit to narrow them.

import {
  guildTools,
  userInterfaceTools,
  pick,
  omit,
} from "@guildai/agents-sdk";
import { gitHubTools } from "@guildai-services/guildai~github";

const tools = {
  ...guildTools,
  ...userInterfaceTools,
  ...pick(gitHubTools, ["github_repos_get", "github_pulls_list"]),
};

guildTools

Platform tools that give agents access to the Guild API — workspaces, agents, triggers, credentials, workspace context, and more. Including guildTools also enables task.guild.

import { guildTools } from "@guildai/agents-sdk";

const tools = { ...guildTools };

Tool naming

Every guild tool is named guild_{endpoint} where {endpoint} is the GuildService method name. For example, get_workspace_contexts becomes guild_get_workspace_contexts.

Tools vs hooks

Most guild tools are synchronous: the runtime calls the Guild API and returns the result immediately. A few are hooks — they may suspend the agent while waiting for user action or an external callback:

Hook tool	What it waits for
`guild_agent_install_request`	User approves agent installation into the workspace
`guild_credentials_request`	User completes an OAuth flow for a third-party service
`guild_experimental_fetch_async`	HTTP response arrives asynchronously
`guild_sleep`	Timer expires

Your agent does not need to handle hook suspension explicitly; the runtime persists the agent’s state, and onToolResults / automatic resumption continues where you left off.

Full endpoint listing

All 55 guild_* tools correspond 1-to-1 with the GuildService methods documented in the Task object — task.guild section, organized into these groups:

Group	Example tools
Current user	`guild_get_me`, `guild_get_my_workspaces`, `guild_get_my_organizations`
Users	`guild_search_users`, `guild_get_user`
Agents	`guild_list_agents`, `guild_create_agent`, `guild_search_agent`, `guild_get_agent_code`
Agent likes	`guild_create_agent_like`, `guild_list_agent_likers`
Organizations	`guild_get_organization`, `guild_get_organization_workspaces`
Workspaces	`guild_get_workspace`, `guild_get_workspace_contexts`, `guild_create_workspace_context`
Triggers	`guild_create_workspace_trigger`, `guild_activate_trigger`, `guild_deactivate_trigger`
Sessions & tasks	`guild_get_session`, `guild_get_task_workspace_agents`
LLM usage	`guild_get_daily_llm_usage`, `guild_get_hourly_llm_usage`
Credentials & install	`guild_credentials_request`, `guild_agent_install_request`
Flow control & HTTP	`guild_sleep`, `guild_experimental_fetch`, `guild_experimental_fetch_async`

See the full tables for descriptions of every endpoint. Both guild_experimental_fetch and guild_experimental_fetch_async accept an optional max_bytes integer parameter that truncates non-JSON text responses to at most that many UTF-8 bytes (appending a [Response truncated to <max_bytes> bytes] marker), while returning JSON responses fully intact. See task.guild for details.

guildai~get_self

guildai~get_self is a built-in internal platform tool that returns the calling agent’s own identity — agent info, running version, session, and workspace — in a single call. No tool set import or credential configuration is required; the runtime provides it automatically to every running agent.

const self = await task.tools.guildai_get_self({})

See Agent self-identification for the full response payload and attribution examples.

userInterfaceTools

Tools for interacting with the user. Including this set also enables task.ui.

Tool	Description
`ui_prompt`	Ask the user a question and block until they respond (hook — suspends execution). The response can include an optional `attachments` array of base64-encoded images or PDFs
`ui_notify`	Fire-and-forget notification, progress update, or error message
`ui_ping`	Health-check the UI surface (mostly for testing)

import { userInterfaceTools } from "@guildai/agents-sdk";

llmAgent wires ui_notify internally so progress notifications (task.ui.notify()) work, but hides it from the model’s tool definitions unless you explicitly add ui_notify (or userInterfaceTools) to the agent’s tools. Add userInterfaceTools explicitly when an llmAgent needs ui_prompt or ui_ping, and include them in coded agents that need user interaction.

consoleTools

Debug and diagnostic logging.

Tool	Description
`console_log`	Log a message at a given level (`debug`, `info`, `warn`, `error`)

import { consoleTools } from "@guildai/agents-sdk";

task.console is always available regardless of whether consoleTools is included. Include consoleTools in llmAgent definitions to give the LLM access to debug logging.

noTools

An explicit empty tool set. Useful when an agent deliberately needs no tools — makes the intent clear instead of passing {}.

import { noTools } from "@guildai/agents-sdk";

export default agent({
  description: "Returns the input unchanged.",
  inputSchema,
  outputSchema,
  tools: noTools,
  run: async (input) => input,
});

Service integrations

Third-party service tools are imported from their own @guildai-services/* packages. Add them to dependencies in your agent’s package.json.

Service	Import
GitHub	`import { gitHubTools } from "@guildai-services/guildai~github"`
Azure DevOps	`import { azureDevOpsTools } from "@guildai-services/guildai~azure-devops"`
Confluence	`import { confluenceTools } from "@guildai-services/guildai~confluence"`
Cypress	`import { cypressTools } from "@guildai-services/guildai~cypress"`
New Relic	`import { newrelicTools } from "@guildai-services/guildai~newrelic"`
TestRail	`import { testrailTools } from "@guildai-services/guildai~testrail"`

Credentials are configured at the organization level in Settings > Credentials at app.guild.ai using either OAuth or an API token, depending on the service configuration. All tools authenticate automatically through the workspace’s connected accounts. For tools backed by a Model Context Protocol server instead of a first-party integration, see MCP integrations — these packages follow a different naming convention.

Selecting specific tools

Use pick to cherry-pick or omit to exclude specific tools from a set:

import {
  pick,
  omit,
  guildTools,
  userInterfaceTools,
} from "@guildai/agents-sdk";
import { gitHubTools } from "@guildai-services/guildai~github";

// Include only what you need
const tools = {
  ...userInterfaceTools,
  ...pick(gitHubTools, [
    "github_repos_get",
    "github_pulls_list",
    "github_issues_create_comment",
  ]),
};

// Or exclude what you don't want
const trimmedGuild = omit(guildTools, [
  "guild_generate_agent_avatar",
  "guild_create_agent_like",
  "guild_delete_agent_like",
]);

Keeping the tool list small reduces the chance of an LLM calling unintended tools and lowers token cost in the tool definitions portion of the prompt.

Reference

Configuration

guildTools

Tool naming

Tools vs hooks

Full endpoint listing

guildai~get_self

userInterfaceTools

consoleTools

noTools

Service integrations

Selecting specific tools

​guildTools

​Tool naming

​Tools vs hooks

​Full endpoint listing

​guildai~get_self

​userInterfaceTools

​consoleTools

​noTools

​Service integrations

​Selecting specific tools

guildTools

Tool naming

Tools vs hooks

Full endpoint listing

guildai~get_self

userInterfaceTools

consoleTools

noTools

Service integrations

Selecting specific tools