main.py, Crew, Flow ou função de fábrica.
Criar um projeto
Terminal
OPENAI_API_KEY em .env para o modelo padrão openai/gpt-6.1-sol e, em seguida, instale e execute:
O scaffold seleciona a Responses API (api: responses) para chamadas de ferramentas com esse modelo. Em projetos YAML/JSON, edite llm.model e llm.api na definição; o template Python lê MODEL do .env e seleciona a Responses API.
Terminal
crewai install cria o arquivo uv.lock. Inclua-o no commit junto com o projeto. Mantenha .env local e use as configurações de ambiente da implantação para as credenciais do provedor.
Conversas locais
O scaffold defineconversational: true, ou Agent(conversational=True) em Python. Em um terminal, crewai run abre a interface de chat conversacional existente. Cada mensagem usa o Agent configurado e suas ferramentas com o histórico da sessão. Defina o flag como false para usar apenas kickoffs independentes.
Terminal
agent.handle_turn(...) e agent.as_flow(). O histórico fica em memória por padrão; configure explicitamente a persistência do Flow para recuperação entre processos. Use uma instância separada de Agent para cada conversa independente. A opção session_id identifica/restaura uma sessão de Flow; ela não transforma um Agent em um servidor concorrente de várias sessões.
Estrutura do projeto
pyproject.toml gerado seleciona a definição do Agent e inclui a configuração e quaisquer ferramentas locais no pacote:
Definir o Agent
A identidade padrão é um Agent CrewAI de uso geral. Editerole, goal e backstory para especializá-lo. As ferramentas de suporte incluídas são exemplos usados apenas quando relevantes; substitua ou remova conforme o caso de uso. Nenhuma skill é instalada por padrão.
Edite agent.yaml:
messages em tempo de execução; não adicione um campo input fixo à definição.
Escolher JSON ou Python
Terminal
agent.json com os mesmos campos:
agent = Agent(...) de src/python_support/agent.py. Use-o quando a definição do Agent exigir lógica em Python.
Tanto .yml quanto .yaml são aceitos. Ao renomear ou mover uma configuração, atualize definition e a lista only-include do wheel em conjunto. Os caminhos das definições devem permanecer dentro da raiz do projeto.
Sem um definition explícito, a descoberta aceita um único arquivo agent.py, agent.json, agent.yml ou agent.yaml na raiz, ou o caminho convencional src/<package>/agent.py. Se vários arquivos forem encontrados, ocorrerá um erro; defina definition para escolher um deles.
Adicionar uma ferramenta personalizada
Use o arquivo incluídotools/support_hours.py como ponto de partida para outra ferramenta:
custom:support_hours carrega uma subclasse de BaseTool a partir de tools/support_hours.py. Adicione as dependências da ferramenta ao pyproject.toml e atualize o arquivo de lock com crewai install. Carregue apenas código de projetos confiáveis: ferramentas personalizadas e referências Python executam código Python durante o carregamento.
Ferramentas e skills de referência
Os exemplos gerados usam dados locais fictícios. Eles não consultam contas, redefinem senhas, emitem reembolsos nem criam tickets.
O diretório
skills/ começa vazio, com apenas .gitkeep para preservá-lo no Git e nos pacotes gerados. Adicione skills/<name>/SKILL.md com name e description no frontmatter para criar uma skill. As skills adicionadas são descobertas como metadados; o Agent pode usar load_skill para carregar instruções relevantes sob demanda.
Caminhos locais de skills em YAML/JSON são resolvidos a partir da raiz do projeto, inclusive quando load_agent_project(path) é chamado de outro diretório. O scaffold Python mantém tools/ e skills/ dentro de src/<package>/ e ancora as skills em agent.py. O wheel e o arquivo de implantação incluem esses arquivos.
Experimente uma solicitação que combine os recursos do exemplo:
Terminal
Passar um histórico de mensagens
messages também aceita uma lista não vazia de mensagens com role/content:
Terminal
Validar e implantar a prévia
Terminal
.env e .venv.
Para uma implantação com um runtime Enterprise compatível com a prévia, use o fluxo de implantação existente descrito na referência da CLI. A API gerenciada aceita a mesma entrada:
Implantações gerenciadas conversacionais
Com o runtime Enterprise experimental compatível, o adaptador interno de Agent defineconversational = True. O chat usa o Agent configurado e suas ferramentas a cada turno. Inicie uma sessão e reutilize seu session_id nas próximas mensagens:
kickoff_id distinto; consulte /status/<kickoff_id> até o turno terminar antes de enviar outra mensagem. A sessão preserva o histórico de usuário/assistente e o passa para um novo Agent a cada turno. A transcrição contém a resposta pública, enquanto os resultados da execução preservam a saída estruturada do Agent e o uso. A duração e a persistência da sessão dependem da configuração de armazenamento do runtime implantado. Sessões distintas têm históricos separados.
POST /kickoff continua disponível para execuções independentes. Localmente, crewai run abre o chat, enquanto crewai run --inputs continua sendo um único kickoff. O scaffold ativa o flag conversacional na definição do Agent; não é necessário escrever um Flow ou main.py.
Esta prévia foi exercitada com uma API nativa e um worker Celery. Streaming de tokens, suporte a restauração/checkpoints, provisionamento nativo de Agent e compatibilidade com contêineres e versões de produção permanecem fora do escopo verificado.