check-crewai-api

Check CrewAI API

Load this before writing or reviewing crewai code: it maps what you probably remember to what crewai 1.15.x actually accepts.

Verified against crewai 1.15.22 and 1.15.23 on 2026-10-01. Live-tested with real LLMs on 2026-10-01. Run crewai version first; if the major/minor differs from 1.15, re-verify version-sensitive rows with the ask-docs skill before trusting them.

1. Three rules before you write anything

1. Unknown keyword arguments are silently ignored. Agent, Task and Crew accept and drop parameters that do not exist. Crew(memory_config={...}) and Task(response_format=Model) construct fine and do nothing. A stale parameter name never raises, so check it exists:

   from crewai import Agent, Crew, Task

   assert "response_model" in Task.model_fields      # real field
   assert "response_format" not in Task.model_fields  # silently dropped if passed
   assert "memory_config" not in Crew.model_fields    # silently dropped if passed
   print(sorted(Agent.model_fields)[:5])

1. The installed source wins over any doc, tutorial, or memory. That includes the AGENTS.md that crewai create writes into new projects. When a row below matters, check the installed signature (see verify-installed-api.md).
2. Assert on structured output at the boundary. Several mistakes below fail quietly with out.pydantic is None while the run reports success.

2. Imports

The current top-level and project imports:

from crewai import Agent, BaseLLM, Crew, CrewOutput, Flow, LLM, Memory, Process, Task, TaskOutput
from crewai.project import CrewBase, after_kickoff, agent, before_kickoff, crew, llm, task, tool
from crewai.tools import BaseTool, tool
from crewai.flow import Flow, and_, listen, or_, persist, router, start
from crewai.knowledge.source.string_knowledge_source import StringKnowledgeSource
from crewai.mcp import MCPServerHTTP, MCPServerSSE, MCPServerStdio
from crewai.events import BaseEventListener, crewai_event_bus

3. Agent, Task, Crew parameters and defaults

from crewai import Agent, Crew, Process, Task

researcher = Agent(
    role="Researcher",
    goal="Find facts about {topic}",
    backstory="A careful researcher.",
    llm="openai/gpt-4.1-mini",
)
research = Task(
    description="List three facts about {topic}.",
    expected_output="Three bullet points.",
    agent=researcher,
)
crew = Crew(agents=[researcher], tasks=[research], process=Process.sequential, cache=True)
out = crew.kickoff(inputs={"topic": "honey bees"})
print(out.raw)

4. Running a crew and reading the result

CrewOutput fields: raw, pydantic, json_dict, tasks_output (a list of TaskOutput), token_usage. out["field"] reads from pydantic/json_dict. kickoff_for_each(inputs=[...]) returns a list of CrewOutput.

token_usage is summed over each agent's LLM object for that object's whole lifetime, not per run. One LLM(...) instance shared by two agents counts every call twice, and one reused across crews carries the earlier crews' tokens (verified with anthropic/claude-haiku-4-5: a second one-call crew on the same LLM reported 148 tokens and 2 requests, a fresh LLM 73 and 1). For per-run cost, give each crew its own LLM objects, or count LLMCallCompletedEvents (event.usage).

import asyncio

from crewai import Agent, Crew, Task



def make_crew() -> Crew:
    writer = Agent(role="Writer", goal="Write", backstory="Writes short text.", llm="openai/gpt-4.1-mini")
    task = Task(description="One line on {topic}.", expected_output="One line.", agent=writer)
    return Crew(agents=[writer], tasks=[task])


out = make_crew().kickoff(inputs={"topic": "bees"})
print(out.raw, out.token_usage.total_tokens, [t.raw for t in out.tasks_output])

many = make_crew().kickoff_for_each(inputs=[{"topic": "bees"}, {"topic": "ants"}])
print([o.raw for o in many])


async def main():
    return await make_crew().akickoff(inputs={"topic": "wasps"})

print(asyncio.run(main()).raw)

5. LLMs, model strings, and provider extras

LiteLLM is no longer a dependency. LLM(model=...) is a factory that returns a native provider class; only the OpenAI SDK ships with core crewai.

Native providers: openai, anthropic/claude, azure, google/gemini, bedrock/aws, openrouter, deepseek, ollama, hostedvllm, cerebras, dashscope, snowflake. Extras: `crewai[anthropic]`, `crewai[google-genai]`, `crewai[bedrock]`, `crewai[azure-ai-inference]`, `crewai[litellm]`. Construction never checks the key; kickoff does (`ValueError: OPENAIAPIKEY is required`, or `ANTHROPICAPI_KEY is required; a wrong key gets the provider's AuthenticationError ... 401). The crewai create scaffolds never add a provider extra, even with --provider anthropic/...: run uv add "crewai[anthropic]"` yourself.

from crewai import LLM

gpt = LLM(model="openai/gpt-4.1-mini", temperature=0.2)  # core install
local = LLM(model="ollama/llama3")                        # core install, OpenAI-compatible route
claude = LLM(model="anthropic/claude-sonnet-4-5")         # needs: uv add "crewai[anthropic]"
print(type(gpt).__name__, type(local).__name__, type(claude).__name__)

A custom LLM subclasses BaseLLM and implements call with the full signature. If call forwards messages to a provider SDK, send only each message's role and content: crewai adds a cache_breakpoint: True key to some messages, and the Anthropic API rejects it with 400 ... messages.0.cache_breakpoint: Extra inputs are not permitted.

from typing import Any

from crewai import Agent, BaseLLM, Crew, Task


class EchoLLM(BaseLLM):
    def call(self, messages, tools=None, callbacks=None, available_functions=None,
             from_task=None, from_agent=None, response_model=None, **kwargs: Any) -> str:
        return "echo: " + str(messages[-1]["content"])[:40]


agent = Agent(role="Echo", goal="Echo", backstory="Echoes.", llm=EchoLLM(model="echo"))
task = Task(description="Say hi", expected_output="Anything", agent=agent)
print(Crew(agents=[agent], tasks=[task]).kickoff().raw)

6. Structured output

from pydantic import BaseModel

from crewai import Agent, Crew, Task


class Report(BaseModel):
    title: str
    points: list[str]


analyst = Agent(role="Analyst", goal="Summarise", backstory="Concise.", llm="openai/gpt-4.1-mini")
task = Task(description="Summarise {topic}.", expected_output="A title and points.",
            agent=analyst, output_pydantic=Report)
out = Crew(agents=[analyst], tasks=[task]).kickoff(inputs={"topic": "bees"})
assert out.pydantic is not None, "structured output was dropped"
print(out.pydantic.title, out["points"])

standalone = analyst.kickoff("Summarise bees.", response_format=Report)
print(standalone.pydantic)

In a @CrewBase project keep the model in Python even when the rest of the task is YAML:

@task
def research_task(self) -> Task:
    return Task(config=self.tasks_config["research_task"], output_pydantic=Report)

7. Guardrails

A function guardrail takes one argument (TaskOutput) and returns a tuple (bool, value). On False the value is fed back to the agent as the error and the task retries, up to guardrail_max_retries (default 3); then the task raises Task failed guardrail validation after N retries. A string guardrail is checked by an extra LLM call.

from typing import Any

from crewai import Agent, Crew, Task, TaskOutput


def under_50_words(output: TaskOutput) -> tuple[bool, Any]:
    if len(output.raw.split()) > 50:
        return (False, "Keep it under 50 words.")
    return (True, output.raw)


writer = Agent(role="Writer", goal="Write", backstory="Brief.", llm="openai/gpt-4.1-mini")
task = Task(description="Describe {topic}.", expected_output="A short paragraph.", agent=writer,
            guardrails=[under_50_words, "Must not mention prices"], guardrail_max_retries=2)
print(Crew(agents=[writer], tasks=[task]).kickoff(inputs={"topic": "bees"}).raw)

guardrails=[...] runs each guardrail in order; a successful string result replaces out.raw for the next one.

8. Memory and knowledge

Memory is one Memory class (LanceDB storage). Its defaults call OpenAI: text-embedding-3-large for embeddings and gpt-5.4-mini for analysis. Crew(memory=True) analyses with the first agent's llm instead, and knowledge with no embedder embeds with text-embedding-3-small. Live with an OpenAI key: a memory=True crew stored a codename in one process and a new crew recalled it in the next; crew and agent knowledge both answered from the source.

The embedder config shape is {"provider": <name>, "config": {...}}; the OpenAI model key is model_name. "model" raises TypeError: ... unexpected keyword argument 'model' in Memory, and for knowledge it is silently ignored (the crew embeds with text-embedding-3-large). The ollama provider below also needs uv add ollama and a running Ollama server with the model pulled; without the package, crew knowledge is silently None. {"provider": "onnx"} is a local, key-free embedder that core crewai can already run (chromadb's onnxruntime; about 80 MB of model downloaded on first use) - the design-agent skill's memory-and-knowledge reference has working examples. For a deterministic embedder in tests, use a callable (Memory) or a custom class (knowledge) - see verify-installed-api.md.

from crewai import Agent, Crew, Memory, Task
from crewai.knowledge.source.string_knowledge_source import StringKnowledgeSource

embedder = {"provider": "ollama", "config": {"model_name": "nomic-embed-text"}}  # needs: uv add ollama
memory = Memory(llm="openai/gpt-4.1-mini", embedder=embedder)
facts = StringKnowledgeSource(content="acme was founded in 2020.")

agent = Agent(role="Analyst", goal="Answer", backstory="Uses knowledge.", llm="openai/gpt-4.1-mini")
task = Task(description="When was acme founded?", expected_output="A year.", agent=agent)
crew = Crew(agents=[agent], tasks=[task], memory=memory, knowledge_sources=[facts], embedder=embedder)
if crew.knowledge is None:
    print("knowledge failed to initialise - is the ollama package installed and the server running?")

Reset stored data from the project directory with crewai reset-memories -m (memory; errors with Memory memory system is not initialized if the crew has no memory), -kn (knowledge), -akn (agent knowledge), -k (latest kickoff outputs), -a (all). The old -s, -l, -e flags are hidden deprecated aliases that print a warning and reset the unified memory. Storage path and offline embedders: verify-installed-api.md.

9. Project scaffold and CLI

crewai version
crewai create crew research_crew --classic --skip-provider
cd research_crew && uv add "crewai[anthropic]"   # only if an agent uses an anthropic/ model
crewai install && crewai run
crewai reset-memories --help

The classic layout: src/<name>/crew.py (@CrewBase class), src/<name>/config/agents.yaml and tasks.yaml (keys match the @agent/@task method names), main.py, and pyproject.toml with [tool.crewai] type = "crew" and dependency crewai[tools]. In YAML, llm: <name> resolves to an @llm method of that name, otherwise it is used as a model string. crewai create flow also writes a .env with a placeholder OPENAI_API_KEY - replace it, never commit it.

10. Removed and deprecated

11. Common mistakes

12. Checklist

• [ ] crewai version checked; rows re-verified if not 1.15.x
• [ ] Every Agent/Task/Crew kwarg exists in model_fields
• [ ] Tools import from crewai.tools, flow decorators and persist from crewai.flow
• [ ] Every task has expected_output
• [ ] Every non-OpenAI model string has its extra in pyproject.toml
• [ ] Structured output set in Python with output_pydantic, and out.pydantic asserted non-None
• [ ] Guardrails return (bool, value) and are annotated tuple[bool, Any] or not at all
• [ ] Memory and knowledge have an explicit embedder or a provider key in the environment
• [ ] No CodeInterpreterTool, allow_code_execution, ShortTermMemory, memory_config
• [ ] Classic projects created with crewai create crew <name> --classic; provider extra added with uv add
• [ ] CI and scripts use classic crews (crewai create crew <name> --classic) run with uv run run_crew

References

• Verify the installed API - one-liners to check fields, defaults and signatures in the installed crewai; storage paths; an offline embedder for memory and knowledge
• Source receipts - the crewai source file and line behind each row, so you can re-check after an upgrade
• Public docs: https://docs.crewai.com

For related skills:

• ask-docs - query the live CrewAI docs when a row may have changed
• getting-started - project scaffolding and choosing crews vs flows
• design-agent / design-task - tuning agents and tasks once the API is right
• build-flow - Flow state, routers, @persist, human feedback
• connect-tools-and-mcp - BaseTool, @tool, mcps=[...]
• test-crewai-project - offline stub LLM and deterministic tests
• deploy-to-amp / call-deployed-crew - shipping and calling a crew