### Install Guild CLI

Source: https://docs.guild.ai/quickstart

Installs the Guild AI command-line interface globally using npm. This is a prerequisite for building and managing agents locally.

```bash
npm install -g @guildai/cli
```

--------------------------------

### Save and Publish Agent

Source: https://docs.guild.ai/quickstart

Saves the current state of the agent with a commit message, waits for validation to complete, and then publishes the agent to make it available in the Guild catalog. This makes the agent installable in workspaces.

```bash
guild agent save --message "First version" --wait --publish
```

--------------------------------

### Install and Authenticate Guild CLI

Source: https://docs.guild.ai/cli/getting-started

Commands to install the Guild CLI globally via npm and perform user authentication. These steps are required to interact with the Guild platform and configure local environments.

```bash
npm i @guildai/cli -g
guild auth login
guild auth status
```

--------------------------------

### Verify Guild CLI Setup

Source: https://docs.guild.ai/cli/introduction

Runs a diagnostic check on the Guild CLI setup, verifying authentication, server connectivity, default workspace, and git configuration. It reports any issues found and suggests potential fixes.

```bash
guild doctor
```

--------------------------------

### Run Guild AI Utilities

Source: https://docs.guild.ai/cli/commands

Utility commands for Guild AI. Includes diagnosing setup issues with 'doctor', installing skills with 'setup', and checking the CLI version with 'version'.

```bash
guild doctor     # Diagnose setup issues (auth, server, workspace, git)
guild setup      # Install coding assistant skills in the current project
guild version    # Show the CLI version
```

--------------------------------

### Verify Guild CLI Installation

Source: https://docs.guild.ai/cli/introduction

Checks if the Guild CLI has been installed correctly by displaying its version number. This is a simple verification step after installation.

```bash
guild --version
```

--------------------------------

### Define an LLM agent with GitHub tools

Source: https://docs.guild.ai/sdk/llm-agents

Demonstrates how to initialize an llmAgent by providing a system prompt and a collection of tools. This example uses GitHub and Guild tools to create a code review assistant.

```typescript
import { guildTools, llmAgent } from "@guildai/agents-sdk"
import { gitHubTools } from "@guildai-services/guildai~github"

const systemPrompt = `
You are a code review assistant.

When given a pull request, retrieve the latest changes
using the GitHub tools and provide helpful feedback.
`

export default llmAgent({
  description: "Reviews pull requests and provides feedback.",
  tools: { ...gitHubTools, ...guildTools },
  systemPrompt,
})
```

--------------------------------

### Basic GitHub Agent Setup

Source: https://docs.guild.ai/services/github

This snippet demonstrates how to initialize an LLM agent with access to all GitHub tools provided by the @guildai-services/guildai~github package. It imports necessary components from the SDK and the GitHub package.

```typescript
import { gitHubTools } from "@guildai-services/guildai~github"
import { llmAgent } from "@guildai/agents-sdk"

export default llmAgent({
  description: "An agent that manages GitHub issues",
  tools: { ...gitHubTools },
})
```

--------------------------------

### Example Guild Doctor Diagnostic Output

Source: https://docs.guild.ai/cli/getting-started

An example output from the `guild doctor` command, showing the status of various checks including authentication, server connection, configuration paths, default workspace, and Git installation. This helps in identifying potential setup issues.

```text
Checking Guild CLI setup...

  ✓ Authentication       Logged in
  ✓ Server               Connected to https://app.guild.ai/api (125ms)
  ✓ Global config        ~/.guild/config.json
  ✓ Default workspace    my-workspace
  - Local config         Not in an agent directory
  ✓ Git                  Installed

5 passed, 0 failed, 1 skipped
```

--------------------------------

### Guild CLI Authentication and Setup Commands

Source: https://docs.guild.ai/cli/getting-started

Provides commands for managing authentication with the Guild platform, selecting workspaces, and setting up coding assistant skills. These commands are crucial for configuring and maintaining your Guild environment.

```bash
guild auth login              # Authenticate with Guild
guild auth logout             # Sign out
guild auth status             # Check authentication
guild workspace select        # Set default workspace
guild doctor                  # Check CLI setup
guild setup                   # Install coding assistant skills
```

--------------------------------

### Authenticate Guild CLI

Source: https://docs.guild.ai/quickstart

Logs into the Guild AI service to authenticate the local CLI. This process opens a browser for sign-in and configures the local npm registry for Guild packages. It also includes a verification command.

```bash
guild auth login

# Verify:

guild auth status
# ✓ Authenticated
```

--------------------------------

### Test Agent Ephemerally

Source: https://docs.guild.ai/quickstart

Tests a locally developed agent in an ephemeral session without saving changes. This command opens an interactive chat interface to test the agent's responses and behavior. Press Ctrl+C to exit the session.

```bash
guild agent test --ephemeral
```

--------------------------------

### Selecting Specific GitHub Tools for an Agent

Source: https://docs.guild.ai/services/github

This example shows how to optimize an agent by selecting only the necessary GitHub tools using the `pick()` function from the Guild AI SDK. This reduces the agent's complexity and improves performance. Tools are prefixed with `github_`.

```typescript
import { gitHubTools } from "@guildai-services/guildai~github"
import { llmAgent, pick } from "@guildai/agents-sdk"

export default llmAgent({
  description: "An agent that reviews pull requests",
  tools: {
    ...pick(gitHubTools, [
      "github_pulls_list",
      "github_pulls_get",
      "github_pulls_list_reviews",
      "github_pulls_create_review",
    ]),
  },
})
```

--------------------------------

### Implement Progress Logging

Source: https://docs.guild.ai/sdk/task-object

Provides an example of using progress notifications to give users real-time feedback during long-running tasks.

```typescript
import { progressLogNotifyEvent } from "@guildai/agents-sdk"

await task.ui?.notify(progressLogNotifyEvent("Creating coding environment..."))
await task.env.create({ baseImage: "node:20" })

await task.ui?.notify(progressLogNotifyEvent("Running tests..."))
const result = await task.env.exec({ command: "npm test" })
```

--------------------------------

### Manage Guild AI CLI Configuration

Source: https://docs.guild.ai/cli/commands

Commands to read and write global CLI configuration values. Supports listing all values, getting a specific key, setting a key-value pair, and showing the configuration file path.

```bash
guild config list               # Show all config values
guild config get <key>          # Read a value
guild config set <key> <value>  # Write a value
guild config path               # Show path to config file
```

--------------------------------

### Manage Guild AI Workspaces

Source: https://docs.guild.ai/cli/commands

Commands for managing workspaces and their contents. Includes listing, creating, selecting, and retrieving workspace details. Also covers managing agents installed within a workspace and handling workspace context versions.

```bash
guild workspace list                    # List all accessible workspaces
guild workspace create <name>           # Create a new workspace
guild workspace get <identifier>        # Get workspace details
guild workspace select                  # Set the default workspace (interactive)
guild workspace select <id-or-name>     # Set the default workspace directly
guild workspace current                 # Show current default workspace
```

```bash
guild workspace agent list                    # List agents installed in workspace
guild workspace agent add <identifier>        # Install an agent
guild workspace agent remove <identifier>     # Remove an agent
```

```bash
guild workspace context list <workspace-id>                      # List context versions
guild workspace context get <workspace-id> <context-id>          # Get a version
guild workspace context edit <workspace-id>                      # Edit in $EDITOR, creates draft
guild workspace context edit <workspace-id> --from <context-id>  # Edit from a specific version
guild workspace context publish <workspace-id> <context-id>      # Publish a draft
```

--------------------------------

### Configure Guild CLI

Source: https://docs.guild.ai/cli/introduction

Manages the global configuration for the Guild CLI, stored in `~/.guild/config.json`. Commands allow listing all configuration values, getting a specific value, and setting a new value. Common configuration keys include `default_workspace`, `debug`, `json`, and `quiet`.

```bash
guild config list
```

```bash
guild config get default_workspace
```

```bash
guild config set debug true
```

--------------------------------

### Initialize a New Agent

Source: https://docs.guild.ai/quickstart

Creates a new agent project directory, initializes it with a specified name and LLM template, and sets up a local Git repository with starter files. The starter files include agent code, package configuration, TypeScript configuration, and local Guild configuration.

```bash
mkdir hello-agent && cd hello-agent
guild agent init --name hello-agent --template LLM
```

--------------------------------

### Initialize Bitbucket tools in an LLM agent

Source: https://docs.guild.ai/services/bitbucket

Demonstrates how to import and register the full suite of Bitbucket tools into a Guild AI agent using the agents-sdk.

```typescript
import { bitbucketTools } from "@guildai-services/guildai~bitbucket"
import { llmAgent } from "@guildai/agents-sdk"

export default llmAgent({
  description: "An agent that manages Bitbucket pull requests",
  tools: { ...bitbucketTools },
})
```

--------------------------------

### GET /conversations.list

Source: https://docs.guild.ai/services/slack

Retrieves a list of all conversations in the workspace.

```APIDOC
## GET /conversations.list

### Description
Returns a list of all channels and conversations available to the authenticated user.

### Method
GET

### Endpoint
/conversations.list

### Query Parameters
- **limit** (integer) - Optional - The maximum number of items to return.

### Response
#### Success Response (200)
- **channels** (array) - A list of conversation objects.

#### Response Example
{
  "ok": true,
  "channels": [
    { "id": "C1", "name": "general" },
    { "id": "C2", "name": "random" }
  ]
}
```

--------------------------------

### Initialize a New Agent Project

Source: https://docs.guild.ai/cli/getting-started

Commands to create a new directory for an agent project and initialize it using the Guild CLI. Supports interactive prompts or flag-based configuration.

```bash
mkdir my-agent && cd my-agent
guild agent init
guild agent init --name my-agent --template LLM
```

--------------------------------

### GET /rest/api/3/permissions

Source: https://docs.guild.ai/services/jira

Retrieves all available permissions from the Jira instance.

```APIDOC
## GET /rest/api/3/permissions

### Description
Retrieves a list of all permissions available in the Jira instance.

### Method
GET

### Endpoint
/rest/api/3/permissions

### Response
#### Success Response (200)
- **permissions** (array) - A list of permission objects.
```

--------------------------------

### GET /users.info

Source: https://docs.guild.ai/services/slack

Retrieves information about a specific user by their ID.

```APIDOC
## GET /users.info

### Description
Fetches detailed information about a user based on their unique user ID.

### Method
GET

### Endpoint
/users.info

### Query Parameters
- **user** (string) - Required - The ID of the user to retrieve.

### Response
#### Success Response (200)
- **user** (object) - The user profile object.

#### Response Example
{
  "ok": true,
  "user": {
    "id": "U123",
    "name": "jdoe"
  }
}
```

--------------------------------

### GET /get_projects

Source: https://docs.guild.ai/services/testrail

Retrieves a list of all projects available in the TestRail instance.

```APIDOC
## GET /get_projects

### Description
Fetches all projects accessible to the authenticated user.

### Method
GET

### Endpoint
/get_projects

### Response
#### Success Response (200)
- **projects** (array) - List of project objects

#### Response Example
{
  "projects": [
    { "id": 1, "name": "Project Alpha" }
  ]
}
```

--------------------------------

### GET /rest/api/3/status/{idOrName}

Source: https://docs.guild.ai/services/jira

Retrieves details for a specific status by its ID or name.

```APIDOC
## GET /rest/api/3/status/{idOrName}

### Description
Fetches metadata for a specific status identified by ID or name.

### Method
GET

### Endpoint
/rest/api/3/status/{idOrName}

### Parameters
#### Path Parameters
- **idOrName** (string) - Required - The ID or name of the status.

### Response
#### Success Response (200)
- **id** (string) - Status ID
- **name** (string) - Status name
```

--------------------------------

### Set up Coding Assistant Skills with Guild CLI

Source: https://docs.guild.ai/cli/introduction

Installs development skills for coding assistants like Claude Code. This command creates necessary files in `.claude/skills/` to provide the assistant with knowledge of the Guild SDK and agent development patterns. The `--force` and `--claude-md` flags offer additional options for updating and generating templates.

```bash
guild setup
```

--------------------------------

### GET /get_results/{test_id}

Source: https://docs.guild.ai/services/testrail

Retrieves the test results for a specific test instance.

```APIDOC
## GET /get_results/{test_id}

### Description
Fetches the history of results for a specific test.

### Method
GET

### Endpoint
/get_results/{test_id}

### Parameters
#### Path Parameters
- **test_id** (integer) - Required - The ID of the test.

### Response
#### Success Response (200)
- **results** (array) - List of result objects

#### Response Example
{
  "results": [
    { "id": 500, "status_id": 1, "comment": "Passed" }
  ]
}
```

--------------------------------

### GET /get_cases/{project_id}

Source: https://docs.guild.ai/services/testrail

Retrieves all test cases associated with a specific project.

```APIDOC
## GET /get_cases/{project_id}

### Description
Fetches a list of test cases for the specified project.

### Method
GET

### Endpoint
/get_cases/{project_id}

### Parameters
#### Path Parameters
- **project_id** (integer) - Required - The ID of the project to fetch cases from.

### Response
#### Success Response (200)
- **cases** (array) - List of test case objects

#### Response Example
{
  "cases": [
    { "id": 101, "title": "Login Test" }
  ]
}
```

--------------------------------

### Select specific Bitbucket tools for agent optimization

Source: https://docs.guild.ai/services/bitbucket

Shows how to use the pick function to include only necessary Bitbucket tools, reducing agent complexity and improving performance.

```typescript
import { bitbucketTools } from "@guildai-services/guildai~bitbucket"
import { llmAgent, pick } from "@guildai/agents-sdk"

export default llmAgent({
  description: "An agent that manages Bitbucket pull requests",
  tools: {
    ...pick(bitbucketTools, [
      "bitbucket_get_repositories_workspace_repo_slug_pullrequests",
      "bitbucket_get_repositories_workspace_repo_slug_pullrequests_pull_request_id",
      "bitbucket_post_repositories_workspace_repo_slug_pullrequests",
      "bitbucket_post_repositories_workspace_repo_slug_pullrequests_pull_request_id_merge",
    ]),
  },
})
```

--------------------------------

### GET /get_project/{project_id}

Source: https://docs.guild.ai/services/testrail

Retrieves details for a specific TestRail project by its ID.

```APIDOC
## GET /get_project/{project_id}

### Description
Retrieves the details of a single project.

### Method
GET

### Endpoint
/get_project/{project_id}

### Parameters
#### Path Parameters
- **project_id** (integer) - Required - The unique identifier of the project.

### Response
#### Success Response (200)
- **id** (integer) - Project ID
- **name** (string) - Project name

#### Response Example
{
  "id": 1,
  "name": "Project Alpha"
}
```

--------------------------------

### Define LLM Agent Logic

Source: https://docs.guild.ai/quickstart

Defines the core logic for a multi-turn LLM agent using the Guild AI SDK. It sets a system prompt for the AI's behavior and includes standard Guild tools for interaction. The `multi-turn` mode enables continuous conversation.

```typescript
import { llmAgent, guildTools } from "@guildai/agents-sdk"

export default llmAgent({
  description: "A friendly greeting agent",
  tools: { ...guildTools },
  systemPrompt: `You are a friendly assistant. Greet users warmly and answer their questions.`,
  mode: "multi-turn",
})
```

--------------------------------

### GET /users/{username}

Source: https://docs.guild.ai/services/github

Endpoints to retrieve specific user profile information and their associated repositories.

```APIDOC
## GET /users/{username}

### Description
Retrieve profile information for a specific GitHub user.

### Method
GET

### Endpoint
/users/{username}

### Parameters
#### Path Parameters
- **username** (string) - Required - The GitHub username

### Response
#### Success Response (200)
- **login** (string) - User handle
- **id** (integer) - User ID
```

--------------------------------

### GET /search/*

Source: https://docs.guild.ai/services/github

Endpoints for searching various GitHub entities including code, commits, issues, repositories, and users.

```APIDOC
## GET /search/code

### Description
Search for code within repositories.

### Method
GET

### Endpoint
/search/code

### Response
#### Success Response (200)
- **items** (array) - List of code search results

---

## GET /search/repositories

### Description
Search for GitHub repositories.

### Method
GET

### Endpoint
/search/repositories

### Response
#### Success Response (200)
- **items** (array) - List of matching repositories
```

--------------------------------

### Cherry-pick tools using Guild AI SDK

Source: https://docs.guild.ai/sdk/tools

Demonstrates how to import tool sets and filter them using the 'pick' function. This approach minimizes the tool surface area provided to an LLM, reducing the risk of incorrect tool invocation.

```typescript
import { pick, userInterfaceTools } from "@guildai/agents-sdk"
import { gitHubTools } from "@guildai-services/guildai~github"

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

--------------------------------

### GET /repos/{owner}/{repo}/pulls/{pull_number}/comments

Source: https://docs.guild.ai/services/github

Retrieve a list of review comments for a specific pull request.

```APIDOC
## GET /repos/{owner}/{repo}/pulls/{pull_number}/comments

### Description
Lists all review comments associated with a specific pull request in a repository.

### Method
GET

### Endpoint
/repos/{owner}/{repo}/pulls/{pull_number}/comments

### Parameters
#### Path Parameters
- **owner** (string) - Required - The account owner of the repository.
- **repo** (string) - Required - The name of the repository.
- **pull_number** (integer) - Required - The number of the pull request.

### Response
#### Success Response (200)
- **comments** (array) - A list of review comment objects.

#### Response Example
{
  "comments": []
}
```

--------------------------------

### Demonstrate serialization limitation with dynamic function references

Source: https://docs.guild.ai/packages/babel-plugin

This example illustrates a limitation where conditionally assigned functions may not survive the serialization process if an agent is suspended at an await point.

```typescript
async function foo(x: number): Promise<number> {
  "use agent"
  const f = x > 0 ? () => x : () => -x
  await delay()
  return f() // f may be lost after deserialization
}
```

--------------------------------

### Initialize Jira Agent with Specific Tools (TypeScript)

Source: https://docs.guild.ai/services/jira

This code snippet shows how to initialize a Guild AI agent with a curated set of Jira tools using the `pick` function. This approach improves agent performance by limiting the number of tools it has access to. It imports `jiraTools`, `llmAgent`, and `pick`, then selects specific tools like 'jira_search_and_reconsile_issues_using_jql', 'jira_get_issue', 'jira_edit_issue', and 'jira_add_comment'.

```typescript
import { jiraTools} from "@guildai-services/guildai~jira"
import { llmAgent, pick } from "@guildai/agents-sdk"

export default llmAgent({
  description: "An agent that triages Jira bugs",
  tools: {
    ...pick(jiraTools, [
      "jira_search_and_reconsile_issues_using_jql",
      "jira_get_issue",
      "jira_edit_issue",
      "jira_add_comment",
    ]),
  },
})
```

--------------------------------

### Initialize Azure DevOps Agent with Specific Tools

Source: https://docs.guild.ai/services/azure-devops

This example demonstrates how to initialize an LLM agent with a curated selection of Azure DevOps tools using the `pick` function from the `@guildai/agents-sdk`. This approach improves agent performance by limiting the available tools to only those required for specific tasks, such as managing work items.

```typescript
import { azureDevOpsTools } from "@guildai-services/guildai~azure-devops"
import { llmAgent, pick } from "@guildai/agents-sdk"

export default llmAgent({
  description: "An agent that manages Azure DevOps work items",
  tools: {
    ...pick(azureDevOpsTools, [
      "azure_devops_work_items_list",
      "azure_devops_work_items_get_work_item",
      "azure_devops_work_items_create",
      "azure_devops_work_items_update",
    ]),
  },
})
```