Framework for orchestrating role-playing, autonomous AI agents. By fostering collaborative intelligence, CrewAI empowers agents to work together seamlessly, tackling complex tasks.
AGENTS.md: working in this CrewAI project
Generated by
crewai createfor coding agents (Claude Code, Codex, Cursor, Copilot and others). Start with Working in this project. Everything after it is reference. CrewAI changes quickly. When an API detail matters, check the installed version (uv run python -c "import crewai; print(crewai.__version__)") and https://docs.crewai.com instead of your training data. If the docs and this file disagree, the docs win.
Working in this project
CrewAI AMP (app.crewai.com) is where this project's runs are traced and evaluated, where the organization keeps its integrations, skills and agents, and where the project is deployed. The steps below use each of these where it fits.
Ask the user first only before actions with outside effects: creating a deployment, writing to real external systems (a Slack channel, a CRM record), publishing to the organization, and comparing models on a deployment (it runs the deployment once per model). Do everything else on this page yourself.
At the start of a session
- Pull and update. If the repo has a remote,
git pull --ff-only. Compare the project's crewai (uv run python -c "import crewai; print(crewai.__version__)") with the latest release (https://pypi.org/pypi/crewai/json,info.version). If it's behind:- Project:
uv lock --upgrade-package crewai --upgrade-package crewai-tools && uv sync. Ifpyproject.tomlexcludes a new major version, read the changelog first and tell the user. - CLI:
uv tool install crewai --upgrade. (crewai updateis something else: it migrates old Poetry projects to uv.)
- Project:
- Check the login. Run
crewai org listand read its output. It exits 0 even when logged out; "Please sign up/login" means logged out.- To log in, run
crewai loginin the background and tell the user to confirm the code it prints in their browser. Then runcrewai org listagain. - Deployments, traces and evaluations go to the active organization (
crewai org current; change it withcrewai org switch <uuid>).
- To log in, run
- Check
.envin the project root: the LLM provider's key,CREWAI_TRACING_ENABLED=true, and, when agents use AMP integrations,CREWAI_ENTERPRISE_ACTION_AUTH_TOKEN(the Enterprise Action Auth Token from AMP's settings, in the project's organization). The user pastes tokens into.envthemselves, never into the chat.
Before writing an agent, a tool or a long prompt, check AMP
The organization may already have it:
- Integrations (Gmail, Slack, HubSpot, Salesforce, Jira, Notion, GitHub and more): give the agent
apps:instead of writing an API client (see "Integrations" under Reference). - Skills: instructions the team keeps on AMP (a brand voice, review rules, an ICP). "AMP skills" under Reference shows how to list and attach them.
- Repository agents: agents defined on AMP's Agent Repository page. Load one with
Agent(from_repository="<handle>").
Write your own only for what isn't there. When the project produces a skill or agent others could reuse, suggest publishing it (crewai skill publish); ask first, since it writes to the organization.
Check every change: evaluate
A change to an agent, task, tool, model, prompt or flow step is done when a traced run passes crewai eval, not when the code runs.
crewai eval, logged in or out, with or without a terminal. When the project changed since its last traced run, it runs the crew first, traced, without asking. It grades the run: a goal gate, a 1–5 grade per area and a report link. Without a terminal it also prints a markdown brief of what failed and the change to make. It exits 0 only when the goal gate passed.- Make the brief's changes, then
crewai evalagain; nocrewai runin between. If a few rounds don't move the grades, change structure first (move decided writes and arithmetic into code, turn criteria the run can't prove into disqualifiers); suggest a stronger model to the user rather than switching it yourself, then stop and report the latest brief.
- The first
crewai evalwriteseval.jsonc. Rewrite its criteria to say what good means for this project. A flow's goal gate is judged against every named task'sexpected_output, so addcriteriaabout the flow's result andassertions(contains,regex) proving promised side effects. Never loosen criteria to make a run pass. A criterion the evidence can't settle works as a disqualifier that applies only when a quoted fact shows it. - When the judge calls a fact unsupported, check the source (the trace's tool output) before changing anything.
- Read the trace before editing when the cause is unclear, and to confirm agents called the tools they were given.
- Your own measurements are welcome on top. Report the
crewai evalresult next to them. - A traced run prints a trace link: the timeline of every agent decision, tool call and LLM call. In an interactive terminal the
crewai runscreen also has a View Traces button (t). - No account is needed to evaluate: don't wait on a login. Logged out, a trace link lasts 24 hours and anyone with it can read it, so check it carries no secrets before sharing; logged in, traces persist on AMP and only the organization's members can open them.
- Logged out, a plain
crewai runwithout a terminal isn't traced (CREWAI_TRACING_ENABLED=truein.envtraces it when logged in, or from a terminal after its prompt); the runcrewai evalstarts always is. crewai eval --models "openai/gpt-4o-mini,anthropic/claude-haiku-4-5"compares models on the deployed project. It needs a login and a deployment and can take an hour. Run it only when the user asks to compare models, never as a fix for failing evals.
To run it anywhere but this machine, deploy to AMP
When the work has to run on a schedule, from a trigger, behind an API or for teammates, deploy it instead of building a server, a Dockerfile, a queue or a cron job.
- Ask before the first
crewai deploy create. It creates a hosted service in the active organization and uploads.envas its environment variables. After that, ship changes withcrewai deploy pushand tell the user. - Before deploying: it runs locally; a flow's last step returns the result (the API returns what
kickoff()returns, so a flow that only writes a file returns nothing);uv.lockis committed;crewai deploy validatepasses. - Deploy:
crewai deploy create -yonce approved (without-yit waits on prompts). With no gitoriginit uploads a ZIP. With anorigin, AMP builds from that remote, on GitHub or another git host: use an HTTPS URL. For GitHub, AMP's GitHub integration needs access to the repo. There's no flag to upload a ZIP when anoriginexists; deploy from a copy without one. - Prove it works:
crewai deploy statusuntil it's online, andcrewai deploy logswhen it isn't. Then run it through its API:POST /kickoff {"inputs": {...}}returns akickoff_id; pollGET /status/{kickoff_id}untilSUCCESSorFAILED. The bearer token is on the deployment's Status tab in AMP and belongs to that deployment, so keep it out of.envand the code. Read the result, and read any side effects back. To prove the deployment runs your current code, compareGET /inspect's flow definition withYourFlow.flow_definition()locally. - Schedules are set in AMP on the deployment page's Scheduling tab; there's no CLI for them yet. Give the user the steps with the time and timezone they asked for.
- Deploy commands can exit 0 after a failed request; confirm with
crewai deploy statusorcrewai deploy list. Remove a deployment withcrewai deploy remove -u <uuid>. - From CI, redeploy with
POST https://app.crewai.com/crewai_plus/api/v1/crews/<deployment-uuid>/deployand a Personal Access Token (AMP Settings → Account) as the bearer. A deployed flow paused on@human_feedbackshowsPAUSEDon/status; answer it in AMP's review dashboard or withPOST https://app.crewai.com/crewai_plus/api/v1/human_feedback_requests/<id>/respondand{"feedback": "..."}, not the deployment's raw/resume_feedback, which leaves AMP's request open.
What only the user can do
- Confirm the login code in the browser.
- Connect an app on AMP's Integrations page (an OAuth step).
- Paste tokens into
.env. - Approve a deployment, writes to real systems, and publishing to the organization.
Never turn off tracing or telemetry to silence errors, speed things up or tidy the setup. Export errors usually mean the network blocks the host: check DNS and proxy settings, and tell the user that before they decide to turn anything off; it's their decision. A sandboxed coding agent needs app.crewai.com, login.crewai.com (login), oss-wharf.crewai.com (traces), crewai-production.s3.us-west-2.amazonaws.com (skill downloads) and docs-platform.crewai.com reachable.
Definition of done
crewai runcompletes from the project root.
- A traced run passes
crewai eval, with criteria written for this project.
- Agents given tools called them (the trace shows it).
- If it has to run elsewhere: deployed with the user's approval, online, and one run through its API returned the expected result.
uv.lockis committed.
Reference
Detailed guides: the CrewAI skill pack for coding agents (npx skills add crewaiinc/skills: building flows, tools, tests, deployments) and https://docs.crewai.com/en/concepts/.
Layouts and commands
- JSON crew (default): edit
agents/*.jsoncandcrew.jsonc; nocrew.py. An agent'stoolstakecustom:<name>for Python tools intools/andplatform:<app>for AMP integrations. Classic crew (--classic):config/agents.yaml,config/tasks.yaml, a@CrewBaseclass increw.py. Flow:src/<pkg>/main.py, crews undersrc/<pkg>/crews/<name>/. uvfor packages, never pip (crewai installsyncs the project). CLI:uv tool install crewai(--upgradeto update). Commituv.lockand[tool.crewai] project_id(crewai login,runanddeploywrite it; never copy it between projects or into a template).crewai run,crewai flow plot,crewai org list,crewai org current,crewai org switch <uuid>,crewai login,crewai traces enable|status,crewai deploy create|push|status|logs|list|validate,crewai deploy remove -u <uuid>,crewai triggers list,crewai triggers run <app>/<trigger>,crewai skill install @<org>/<handle>,crewai reset-memories -m(memory;-knknowledge),crewai log-tasks-outputsandcrewai replay -t <task_id>(rerun from a task),crewai create crew|flow|tool|skill <name>(the oldcrewai tool createstyle still works but warns).crewai testandcrewai trainare legacy.
Core API
- Classic crew: a
@CrewBaseclass setsagents_config = "config/agents.yaml"andtasks_config = "config/tasks.yaml";@agentand@taskmethods are named like the YAML keys and buildAgent(config=self.agents_config["name"]) # type: ignore[index];@crewreturnsCrew(agents=self.agents, tasks=self.tasks, process=Process.sequential). - Tasks need a
description, anexpected_outputand anagent;context=[other_task]feeds earlier outputs in,output_filewrites the result (creating folders:create_directory=Trueby default),human_input=Truehas a person review the result before the crew moves on, and{var}placeholders are filled fromkickoff(inputs={...}). crew.kickoff(inputs={...})returns aCrewOutput(.raw,.pydantic,.json_dict,.tasks_output,.token_usage). Agent limits:max_iter,max_execution_time,max_rpm;respect_context_window=True(the default) summarizes history when it nears the model's context limit;inject_date=Trueputs today's date in the agent's prompt.- Tools: subclass
BaseTool(name,description,args_schema,_run) or decorate a function with@tool("Name")(from crewai.tools import tool; the docstring is the description). - Flows: subclass
Flow[MyState](a Pydantic model; read and writeself.state.x);from crewai.flow import Flow, start, listen, router.@start()marks entry points;@listen(step)runs afterstepwith its return value;@router(step)returns a label (-> Literal["a", "b"]oremit=[...]) that@listen("a")handlers take, and a handler must not be named after its label. In a step, run a crew withMyCrew().crew().kickoff(inputs={...}). - Classic crews and flows start from
src/<pkg>/main.py, whichcrewai runand AMP look for: a crew exposesrun(), a flowkickoff(). Python 3.10 to 3.13.
Facts models get wrong
- LLMs:
Agent(llm="openai/gpt-4o")orcrewai.LLM(model=...), neverChatOpenAI. Providers outside the native set (OpenAI, Anthropic, Azure, Gemini, Bedrock, OpenRouter, DeepSeek, Ollama and more), such asgroq/..., need LiteLLM:uv add 'crewai[litellm]'. OpenAI's Responses API:LLM(model="openai/...", api="responses"). - Flow inputs are state fields with defaults;
kickoff(inputs={...})and trigger payloads (the@start()method'screwai_trigger_payloadparameter) override them. Never overwrite inputs in@start().crewai runtakes no--inputsfor a Python flow. - A flow's last step returns its result; a deployed flow that returns nothing has an empty API result.
- Agents judge, code computes: have agents return per-criterion judgments with evidence (
output_pydantic), and compute scores and branch on them in the flow. - Memory across runs in a flow:
self.remember("text")andself.recall("query")(matches have.record.content); AMP shows it on the deployment's Memory tab. NoMemory()orCrew(memory=True)inside a flow; share it withCrew(memory=self.memory.slice(scopes=[...], read_only=True)). Memory is rooted at the flow's class name, so renaming the class starts a new root.@persist(from crewai.flow import persist) saves state per run: continue one withkickoff(inputs={"id": ...}), or seed a new run from it withkickoff(restore_from_state_id=...). tool_failure_policy="raise"on an agent, task or crew turns a failed tool call into an error. A write can still fail silently, so have the task return the IDs it wrote and raise in the flow when one is missing.- One agent and one prompt don't need a crew:
Agent(...).kickoff("...", response_format=MyModel)returns.rawand.pydantic(kickoff_asyncin async code, such as a flow step). - Deprecated agent options, don't add them:
reasoning(useplanning_config),multimodal(pass files natively),allow_code_execution(use a sandbox tool),function_calling_llm(setllm). Tool-result caching is opt-in:Crew(cache=True). - Integrations: selectors are
app[/action][@connection](gmailloads every action,gmail/send_emailone, which gives better tool choices). Connect the app on AMP's Integrations page;CREWAI_ENTERPRISE_ACTION_AUTH_TOKENin.env;apps: [slack/send_message]in YAML orCrewaiPlatformTools(apps=[...]). Supported apps are in the installedcrewai_core/platform_apps.py(PLATFORM_APPS); print[t.name for t in CrewaiPlatformTools(apps=["slack"])]to see the live actions and copy selectors from those; a selector must load at least one tool (CrewAI warns only when none of an agent's selectors load anything, so check each). Before the first write to a real system, run a read-only action and agree a test target (a test channel or record) with the user. - AMP skills:
crewai skill listshows installed ones only. List the organization's withuv run python -c "from crewai_cli.skills.main import SkillCommand; [print(s['handle'], s['latest_version'], '-', s['description'][:90]) for s in SkillCommand().plus_api_client.list_skills().json()['data']]". Attach under the agent'sskills:as"@<org-uuid>/<handle>@<version>"; load into every prompt withskills=load_skills([...])(from crewai.skills import load_skills). Skills resolve from./skills/<handle>/, then~/.crewai/skills/, then a download. .env: the LLM key,MODEL=for the default model,CREWAI_TRACING_ENABLED=true, andCREWAI_ENTERPRISE_ACTION_AUTH_TOKENfor integrations. Never a deployment's URL or token:.envis uploaded on deploy. List every new variable in.env.example.
Also available
Not used by default; reach for these when the task calls for them. Each line ends with its docs path under https://docs.crewai.com/en/.
- Guardrails:
Task(guardrail=fn_or_"rule")orguardrails=[...];fn(output)gets theTaskOutputand returns(True, value)to accept or(False, feedback)to make the agent retry.concepts/tasks#task-guardrails - Structured task output:
Task(output_pydantic=Model)oroutput_json=Model; readresult.pydanticor.json_dict.concepts/tasks - Knowledge:
knowledge_sources=[StringKnowledgeSource(content=...), PDFKnowledgeSource(file_paths=[...])]on an agent or crew.concepts/knowledge - Hierarchical crews:
Crew(process=Process.hierarchical, manager_llm=...)ormanager_agent=; delegation isAgent(allow_delegation=True).learn/hierarchical-process - Planning:
Agent(planning_config=PlanningConfig(...))makes an agent plan its approach before acting and replan as it goes (from crewai import PlanningConfig; it replacesreasoning=True);Crew(planning=True)plans the crew's tasks up front.concepts/planning - Async and batch:
await crew.akickoff(...),kickoff_for_each(inputs=[...]),akickoff_for_each.learn/kickoff-async - Streaming:
stream=Trueon a crew or flow; iterate whatkickoff()returns, then read.result.concepts/streaming - Events: subclass
BaseEventListener, register handlers with@crewai_event_bus.on(Event)insetup_listeners, instantiate it once.concepts/event-listener - Hooks:
@on(InterceptionPoint.PRE_TOOL_CALL)(alsoPOST_TOOL_CALL,PRE_MODEL_CALL,POST_MODEL_CALL;from crewai.hooks import on, InterceptionPoint, HookAborted) runs on every tool or LLM call without changing the agents: editctx.tool_input, return a string to replace a result, raiseHookAbortedto block. Kickoff hooks:@before_kickoffand@after_kickoffin a@CrewBaseclass.learn/execution-hooks - MCP:
Agent(mcps=["https://.../mcp", "<connected-slug>", MCPServerStdio(...)])(from crewai.mcp import MCPServerStdio).mcp/overview - A2A:
Agent(a2a=A2AClientConfig(endpoint=...))calls a remote agent;A2AServerConfigexposes one (from crewai.a2a import A2AClientConfig, A2AServerConfig). - Human feedback in flows:
@human_feedback(message=..., emit=["approved", "rejected"], llm=...)routes a step on the reply.learn/human-feedback-in-flows - Chat:
crewai chattalks to a classic crew (itschat_llm, elseMODEL; JSON crews aren't supported yet), andcrewai runopens chat for a flow withconversational = True. Both need a terminal, so the user runs them; test a flow's turns withflow.handle_turn(msg, session_id=...)orstream_turn.guides/flows/conversational-flows - Declarative flows:
crewai create flow <name> --declarativekeeps the flow inflow.yaml.concepts/cli - Checkpoints:
Crew(checkpoint=True); resume withkickoff(from_checkpoint=CheckpointConfig(restore_from=path)).concepts/checkpointing - Flow conditions:
@listen(or_(a, b)),and_(a, b);flow.plot()draws the graph.concepts/flows - Tools:
crewai_toolshas 100+ (SerperDevTool,ScrapeWebsiteTool,FileReadTool); check it before writing one.tools/overview - Files:
kickoff(input_files={"chart": ImageFile(source="chart.png")})(from crewai_files import ImageFile).concepts/files