Quickstart

You need a Guild account at app.guild.ai for both parts. The second part also needs Node.js 22 or later for the Guild CLI.

Run an agent

Go to app.guild.ai and sign in with your Google or GitHub account, or enter your email to receive a passwordless magic link. Signing in lands you on the chat page; new accounts also see a short survey dialog, which you can complete, skip, or dismiss with Escape.

Create a workspace

Click Workspaces in the left nav, then click New Workspace and give it a name.

Install an agent

Inside your workspace, click Agents in the left nav and click Add Agent. On the All tab, find an agent and add it (try github-issues if you have a GitHub integration, or any public agent).

Start a session

Click Chat in the workspace’s left nav. Type @ and pick your agent, type a message, and press Enter.The agent runs and responds in the session panel. It may ask clarifying questions or request access to services along the way.

To connect GitHub, Slack, Jira, or other services, go to Access & setup > Credentials and click Connect for each service.

Build your own agent

Paste this into your coding agent (Claude Code, Cursor, Codex, etc.) to get started:

Coding agent prompt

Install the Guild CLI globally with npm: npm install -g @guildai/cli
Authenticate by running: guild auth login --non-interactive
This will print a URL. Tell me to open it in my browser to complete authentication, then wait for the command to finish.
After auth succeeds, run: guild setup --provider <claude, codex, or gemini — whichever you are> --yes
This will install skills for guild agent development and Factory setup.
Then select the home workspace: guild workspace select home
Then list agent categories with: guild agent categories
Create a new agent, picking a category from that list: guild agent init --name hello-agent --template LLM --category <category>
If I belong to an organization, ask me which account should own the agent and add --owner <name>.
Then change into the hello-agent directory it creates.
Edit agent.ts to be a friendly greeting agent using llmAgent with multi-turn mode and guildTools.
Test the agent with: echo '{"prompt":"Hello!"}' | guild agent test --mode json
Ask me if the response looks good. Once I confirm, save and publish with: guild agent save --message "First version" --wait --publish

Or follow the steps below manually. Ready to build a custom agent? The Guild CLI handles the full workflow: create, test, save, publish.

Prerequisites

Node.js 22+ and npm (see nodejs.org)

Install and authenticate

Install the CLI

npm install -g @guildai/cli

Authenticate with Guild

guild auth login

This opens your browser to sign in at app.guild.ai and configures your local npm registry for Guild packages.Verify:

guild auth status
# ✓ Authenticated

If something goes wrong, run guild doctor to diagnose your setup. See the CLI troubleshooting section for common issues.

Create, test, publish

Create the agent

guild agent init --name hello-agent --template LLM
cd hello-agent

If your account belongs to one or more organizations, --owner <name-or-id> is required in non-interactive mode (scripted or CI use). Set a default with guild config set default_owner <name-or-id> to avoid passing it on every invocation.

This scaffolds a hello-agent/ directory, creates the agent in the Guild backend, initializes a local git repo, and pulls starter files:

hello-agent/
├── agent.ts          # Your agent code
├── package.json      # Dependencies (runtime packages are pre-configured)
├── tsconfig.json     # TypeScript config
├── guild.json        # Local config (managed by the CLI)
└── .gitignore

Edit the agent

Open agent.ts and replace the contents:

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",
})

mode: "multi-turn" keeps the conversation going after each response. llmAgent wires ui_notify internally so progress notifications (task.ui.notify()) work, but hides it from the model unless you explicitly add ui_notify to your agent’s tools. Add userInterfaceTools explicitly if your agent needs ui_prompt or ui_ping.

The description field is optional and deprecated as of @guildai/agents-sdk 0.4.0. Guild generates the agent’s published description automatically from its code, so setting description no longer affects the published description.

Select a workspace

guild workspace select

This prompts you to pick a workspace interactively. You can also pass --workspace <id> to guild agent test directly.

Test it

guild agent test

This opens an interactive chat session. Ephemeral versions are created automatically when testing from a local agent directory:

You: Hello!
Agent: Hello! Welcome. I'm happy to help. What can I do for you today?

Press Ctrl+C to exit.

Save and publish

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

--wait blocks until validation passes
--publish implies --wait and makes the agent available to your organization once validation and publish both finish

Your agent is live. Install it in a workspace to use it.For details on publishing workflows, see Publish to the Agent Hub.

Next steps

CLI reference

Full development loop: templates, testing, publishing, troubleshooting.

Agent SDK

Build advanced agents with typed inputs, tool sets, and platform services.

Native agents

A prompt and a tool list, with no code (the simplest way to build).

Agent types

Compare every type: Native, TypeScript, Goose, OpenClaw, and LangGraph.

TypeScript LLM agents

Prompt-driven agents with tools, in TypeScript.

Auto-managed state agents

Deterministic TypeScript agents for algorithmic workflows.

Example agents

Complete agents to add to a workspace, run, and adapt.

Overview

The Smith

The Factory

Platform

Agent SDK

Run an agent

Build your own agent

Prerequisites

Install and authenticate

Create, test, publish

Next steps

CLI reference

Agent SDK

Native agents

Agent types

TypeScript LLM agents

Auto-managed state agents

Example agents

​Run an agent

​Build your own agent

​Prerequisites

​Install and authenticate

​Create, test, publish

​Next steps

CLI reference

Agent SDK

Native agents

Agent types

TypeScript LLM agents

Auto-managed state agents

Example agents

Run an agent

Build your own agent

Prerequisites

Install and authenticate

Create, test, publish

Next steps