Skip to content

Framework for orchestrating role-playing, autonomous AI agents. By fostering collaborative intelligence, CrewAI empowers agents to work together seamlessly, tackling complex tasks.

19.4 KB
Raw Blame

AGENTS.md: working in this CrewAI project

Generated by crewai create for 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

  1. 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. If pyproject.toml excludes a new major version, read the changelog first and tell the user.
    • CLI: uv tool install crewai --upgrade. (crewai update is something else: it migrates old Poetry projects to uv.)
  2. Check the login. Run crewai org list and read its output. It exits 0 even when logged out; "Please sign up/login" means logged out.
    • To log in, run crewai login in the background and tell the user to confirm the code it prints in their browser. Then run crewai org list again.
    • Deployments, traces and evaluations go to the active organization (crewai org current; change it with crewai org switch <uuid>).
  3. Check .env in 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 .env themselves, 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.

  1. 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.
  2. Make the brief's changes, then crewai eval again; no crewai run in 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 eval writes eval.jsonc. Rewrite its criteria to say what good means for this project. A flow's goal gate is judged against every named task's expected_output, so add criteria about the flow's result and assertions (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 eval result 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 run screen 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 run without a terminal isn't traced (CREWAI_TRACING_ENABLED=true in .env traces it when logged in, or from a terminal after its prompt); the run crewai eval starts 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.

  1. Ask before the first crewai deploy create. It creates a hosted service in the active organization and uploads .env as its environment variables. After that, ship changes with crewai deploy push and tell the user.
  2. 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.lock is committed; crewai deploy validate passes.
  3. Deploy: crewai deploy create -y once approved (without -y it waits on prompts). With no git origin it uploads a ZIP. With an origin, 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 an origin exists; deploy from a copy without one.
  4. Prove it works: crewai deploy status until it's online, and crewai deploy logs when it isn't. Then run it through its API: POST /kickoff {"inputs": {...}} returns a kickoff_id; poll GET /status/{kickoff_id} until SUCCESS or FAILED. The bearer token is on the deployment's Status tab in AMP and belongs to that deployment, so keep it out of .env and the code. Read the result, and read any side effects back. To prove the deployment runs your current code, compare GET /inspect's flow definition with YourFlow.flow_definition() locally.
  5. 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.
  6. Deploy commands can exit 0 after a failed request; confirm with crewai deploy status or crewai deploy list. Remove a deployment with crewai deploy remove -u <uuid>.
  7. From CI, redeploy with POST https://app.crewai.com/crewai_plus/api/v1/crews/<deployment-uuid>/deploy and a Personal Access Token (AMP Settings → Account) as the bearer. A deployed flow paused on @human_feedback shows PAUSED on /status; answer it in AMP's review dashboard or with POST https://app.crewai.com/crewai_plus/api/v1/human_feedback_requests/<id>/respond and {"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 run completes 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.lock is 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/*.jsonc and crew.jsonc; no crew.py. An agent's tools take custom:<name> for Python tools in tools/ and platform:<app> for AMP integrations. Classic crew (--classic): config/agents.yaml, config/tasks.yaml, a @CrewBase class in crew.py. Flow: src/<pkg>/main.py, crews under src/<pkg>/crews/<name>/.
  • uv for packages, never pip (crewai install syncs the project). CLI: uv tool install crewai (--upgrade to update). Commit uv.lock and [tool.crewai] project_id (crewai login, run and deploy write 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; -kn knowledge), crewai log-tasks-outputs and crewai replay -t <task_id> (rerun from a task), crewai create crew|flow|tool|skill <name> (the old crewai tool create style still works but warns). crewai test and crewai train are legacy.

Core API

  • Classic crew: a @CrewBase class sets agents_config = "config/agents.yaml" and tasks_config = "config/tasks.yaml"; @agent and @task methods are named like the YAML keys and build Agent(config=self.agents_config["name"]) # type: ignore[index]; @crew returns Crew(agents=self.agents, tasks=self.tasks, process=Process.sequential).
  • Tasks need a description, an expected_output and an agent; context=[other_task] feeds earlier outputs in, output_file writes the result (creating folders: create_directory=True by default), human_input=True has a person review the result before the crew moves on, and {var} placeholders are filled from kickoff(inputs={...}).
  • crew.kickoff(inputs={...}) returns a CrewOutput (.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=True puts 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 write self.state.x); from crewai.flow import Flow, start, listen, router. @start() marks entry points; @listen(step) runs after step with its return value; @router(step) returns a label (-> Literal["a", "b"] or emit=[...]) that @listen("a") handlers take, and a handler must not be named after its label. In a step, run a crew with MyCrew().crew().kickoff(inputs={...}).
  • Classic crews and flows start from src/<pkg>/main.py, which crewai run and AMP look for: a crew exposes run(), a flow kickoff(). Python 3.10 to 3.13.

Facts models get wrong

  • LLMs: Agent(llm="openai/gpt-4o") or crewai.LLM(model=...), never ChatOpenAI. Providers outside the native set (OpenAI, Anthropic, Azure, Gemini, Bedrock, OpenRouter, DeepSeek, Ollama and more), such as groq/..., 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's crewai_trigger_payload parameter) override them. Never overwrite inputs in @start(). crewai run takes no --inputs for 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") and self.recall("query") (matches have .record.content); AMP shows it on the deployment's Memory tab. No Memory() or Crew(memory=True) inside a flow; share it with Crew(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 with kickoff(inputs={"id": ...}), or seed a new run from it with kickoff(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 .raw and .pydantic (kickoff_async in async code, such as a flow step).
  • Deprecated agent options, don't add them: reasoning (use planning_config), multimodal (pass files natively), allow_code_execution (use a sandbox tool), function_calling_llm (set llm). Tool-result caching is opt-in: Crew(cache=True).
  • Integrations: selectors are app[/action][@connection] (gmail loads every action, gmail/send_email one, which gives better tool choices). Connect the app on AMP's Integrations page; CREWAI_ENTERPRISE_ACTION_AUTH_TOKEN in .env; apps: [slack/send_message] in YAML or CrewaiPlatformTools(apps=[...]). Supported apps are in the installed crewai_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 list shows installed ones only. List the organization's with uv 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's skills: as "@<org-uuid>/<handle>@<version>"; load into every prompt with skills=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, and CREWAI_ENTERPRISE_ACTION_AUTH_TOKEN for integrations. Never a deployment's URL or token: .env is 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") or guardrails=[...]; fn(output) gets the TaskOutput and returns (True, value) to accept or (False, feedback) to make the agent retry. concepts/tasks#task-guardrails
  • Structured task output: Task(output_pydantic=Model) or output_json=Model; read result.pydantic or .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=...) or manager_agent=; delegation is Agent(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 replaces reasoning=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=True on a crew or flow; iterate what kickoff() returns, then read .result. concepts/streaming
  • Events: subclass BaseEventListener, register handlers with @crewai_event_bus.on(Event) in setup_listeners, instantiate it once. concepts/event-listener
  • Hooks: @on(InterceptionPoint.PRE_TOOL_CALL) (also POST_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: edit ctx.tool_input, return a string to replace a result, raise HookAborted to block. Kickoff hooks: @before_kickoff and @after_kickoff in a @CrewBase class. 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; A2AServerConfig exposes 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 chat talks to a classic crew (its chat_llm, else MODEL; JSON crews aren't supported yet), and crewai run opens chat for a flow with conversational = True. Both need a terminal, so the user runs them; test a flow's turns with flow.handle_turn(msg, session_id=...) or stream_turn. guides/flows/conversational-flows
  • Declarative flows: crewai create flow <name> --declarative keeps the flow in flow.yaml. concepts/cli
  • Checkpoints: Crew(checkpoint=True); resume with kickoff(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_tools has 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