crewai, 1.15 as of November 2026) for role-based agent crews and event-driven flows. A crew is a set of agents, each with a role, a goal, and a backstory, working through tasks in a sequential or hierarchical process. A flow wires crews and plain code together with @start, @listen, and @router. CrewAI AMP deploys crews and gives them a REST API, app triggers, and traces.
Guild doesn’t run CrewAI code. A crew moves to Guild by rewriting it: crews that are only prompts become Native agents, and crews with several steps, typed output, or flows become TypeScript agents.
Who this is for
Teams with CrewAI crews or flows, run locally, on their own servers, or on CrewAI AMP, who want them in a shared workspace. On Guild, credentials stay behind a proxy, admins set ALLOW/DENY policies on each operation, and every run shows in one place.Concept map
Before you start
Inventory
CrewAI projects come in three shapes. Most existing repositories use the classic one:crew.py with @CrewBase, plus config/agents.yaml and config/tasks.yaml. Newer projects from crewai create crew put crew.jsonc and agents/<name>.jsonc at the root. Declarative flows use a flow.yaml.
List these before writing any Guild code. Record names only, never secret values.
- Every agent’s role, goal, and backstory, and every task’s description and expected output.
- Each
{placeholder}in those files. They’re filled fromkickoff(inputs=...)and become fields on the Guild agent’s input. - The process (sequential or hierarchical), and which agents set
allow_delegation=True. - For flows, each
@start,@listen, and@routermethod and the state it reads or writes. - Every tool:
crewai_toolsimports, customBaseToolor@toolcode and what it calls,apps=[...], andmcps=[...]orMCPServerAdapterservers. - Tasks with
human_input=True,output_pydantic,output_json,guardrail, oroutput_file. - Memory, knowledge sources under
knowledge/, and@persistor checkpoint settings. - AMP triggers turned on for the deployment, and environment variables, by name only.
Steps
- Crew of prompts → Native
- Sequential crew or flow → TypeScript
Use this path when the crew’s tasks are prompts that pass text along and its tools come from integrations.
1
Scaffold a Native agent
--category and --owner stop the CLI from prompting, which a script or coding agent can’t answer. List categories with guild agent categories.2
Fold the roles and tasks into PROMPT.md
Write one set of instructions that covers each agent’s role and goal and each task in order. Replace every
{placeholder} with a sentence that tells the agent what to ask for or expect in the request.PROMPT.md
3
Declare the tools in guild.yaml
Each Check the real names with
apps=[...] entry or crewai_tools tool becomes a Guild integration with only the operations the agent calls:guild.yaml
guild integration list and guild integration operation list <owner~integration> --json. The ones above are illustrative.4
Test
guild agent test collects files by walking your local directory and honoring .gitignore, the same way guild agent save does, so new files such as logic.ts are uploaded even without git add.The first
guild agent save --wait --publish after guild agent init fails with “No saved state… use —force” because of the .gitignore the scaffold writes. Add --force to that first save for now.guild agent save --publish. The Action needs an account API key with the agents:write scope:
Credentials and policies
Remove model provider keys from.env; Guild routes model calls through its own proxy. Recreate each tool’s API key or AMP integration connection as a Guild credential. Use member scope where the crew relied on user_bearer_token, so each person’s runs use their own account. Non-secret settings become workspace variables.
Guild splits a tool approval into two controls:
- Who can call it. Add a credential policy rule scoped to the agent and workspace that allows or denies the operation. DENY wins over ALLOW.
- Sign-off on each call. Add the
ui_promptbuilt-in and have the agent confirm with the user before it calls the tool. The run pauses until someone answers.
What doesn’t map 1:1
Hierarchical crews
Hierarchical crews
A hierarchical crew’s manager delegates through tools CrewAI injects (“Delegate work to coworker” and “Ask question to coworker”). Guild has no automatic manager. Write each delegation as a call to a specialist Guild agent with
guildAgentTool, from a lead agent that decides which specialist to call.Crew Studio
Crew Studio
Crew Studio’s visual canvas has no Guild equivalent. Guild agents are instructions or code.
Self-hosting
Self-hosting
The CrewAI framework runs anywhere under MIT, and AMP can be self-hosted as CrewAI Factory. Guild is a hosted platform, so self-hosted crews move to Guild’s runtime.
Memory, knowledge, and saved state
Memory, knowledge, and saved state
CrewAI memory (LanceDB under
./.crewai/memory), knowledge sources with embeddings, @persist flow state, and checkpoints all live on disk. Guild agents don’t keep files between runs and have no vector memory. Put short reference text in the instructions or an OpenClaw skill, and keep durable state in an outside store reached through an integration.Tool hooks, callbacks, and planning
Tool hooks, callbacks, and planning
Tool hooks (
@before_tool_call, @after_tool_call), step_callback, task_callback, and planning=True have no direct equivalent. Use credential policies to limit which operations the agent can call, and write checks as code in run().Human input
Human input
human_input=True blocks on a console prompt locally and pauses with /resume on AMP. On Guild, the agent asks with ui_prompt and the run pauses until someone answers in the session. A run started by a schedule or webhook waits the same way.Test and training runs
Test and training runs
crewai test, crewai train, and crewai eval don’t run on Guild. Rebuild the important cases as Guild Evaluations or guild agent test sessions. If the repository has a trained_agents_data.pkl, fold its useful suggestions into the instructions.Local MCP servers
Local MCP servers
Guild connects to remote MCP servers by URL. A local stdio server, such as an
MCPServerStdio that runs npx, needs a hosted HTTP endpoint first. Otherwise, move its tools to an integration built from the service’s OpenAPI spec.Three ways to migrate
guild-migrate skill
Ask your coding agent: “Migrate this CrewAI crew to Guild.” It picks Native or TypeScript and writes
MIGRATION.md.Publish Agent to Guild Action
Commit the port to your repository, then publish it from GitHub Actions with an account API key.
Migration agent
Point Migrate to Guild at your repository; it opens a draft pull request. The guild-migrate skill ships in the same package.
Related pages
TypeScript agents
agent(), run, typed input and output, and the task object.LLM calls
task.llm.generateText with structured output.