mirror of
https://github.com/crewAIInc/crewAI.git
synced 2026-07-04 06:29:22 +00:00
feat: adopt directory-based docs versioning with Edge channel
Switch docs.crewai.com from navigation-only versioning (every version selector entry rendered the same docs/<lang>/* source files) to Mintlify's directory-based versioning so each version selector entry renders its own snapshot. Add an "Edge" channel under docs/edge/<lang>/* that always reflects main HEAD for unreleased work, eliminating pre-release leakage onto frozen release labels. External links to canonical /<lang>/* URLs are preserved via wildcard redirects that always land on the current default version. Layout: - docs/edge/<lang>/* rolling source (you edit here) - docs/edge/enterprise-api.*.yaml - docs/v<X.Y.Z>/<lang>/* frozen, immutable snapshots - docs/v<X.Y.Z>/enterprise-api.*.yaml - docs/images/ shared, append-only - docs/docs.json nav + redirects URLs follow the Mintlify-idiomatic shape: /edge/<lang>/<page> for Edge, /v<X.Y.Z>/<lang>/<page> for every frozen snapshot. The wildcard redirects /<lang>/:slug* -> /<default>/<lang>/:slug* keep stale links working, and every freeze rewrites them (plus all per-section/per-page redirects) so destinations always resolve to the current default without depending on a second redirect hop. Release flow integration (devtools release): - New module crewai_devtools.docs_versioning.freeze() materialises docs/v<X.Y.Z>/ from docs/edge/, rewrites openapi: refs inside the snapshot, inserts the version into every language block in docs.json, and refreshes all redirect destinations. - _update_docs_and_create_pr() in cli.py now calls that freeze during Phase 2 of devtools release. Edge changelogs are updated first (so the snapshot freeze picks them up), then the snapshot is staged alongside docs.json, branched as docs/freeze-v<X.Y.Z>, and the PR is titled [docs-freeze] docs: snapshot and changelog for v<X.Y.Z> — the title prefix the new CI guard reads. - The PR still gates tag, GitHub release, PyPI publish, and the enterprise release as before; no new PRs are added. - Pre-releases (1.X.YaN, 1.X.YbN, ...) skip the snapshot — they ride Edge — and the docs PR title omits the [docs-freeze] prefix. - docs_check (AI-generated docs scaffolding) writes to docs/edge/<lang>/* so newly-generated unreleased docs land in Edge and never accidentally touch a frozen snapshot. Migration scripts (one-shot): - scripts/docs/freeze_historical_versions.py reconstructs all 16 historical snapshots (v1.10.0 .. v1.14.7) from git tags via git archive | tar, rewriting openapi: MDX refs so each snapshot reads its own enterprise-api YAML rather than the live one. - scripts/docs/prefix_version_paths.py one-shot-migrates docs.json: rewrites every page path in 16 versioned blocks to point under docs/v<X.Y.Z>/, inserts a new Edge entry per language, tags v1.14.7 as Latest (default), prunes pages whose target file doesn't exist in the snapshot (e.g. docs/ar/ didn't exist before v1.12.0), and writes the wildcard + per-section redirects. - scripts/docs/freeze_current_edge.py is now a thin CLI wrapper around docs_versioning.freeze for manual one-off freezes (e.g. retroactively snapshotting a forgotten release). CI guards (.github/workflows/docs-snapshots.yml): - Frozen snapshots under docs/v[0-9]*/ are immutable; only PRs whose title contains [docs-freeze] (i.e. release-cut PRs generated by devtools release or the manual wrapper) may modify them. - Images under docs/images/ are append-only since snapshots share a single image directory. Deleting or renaming an image breaks every historical snapshot that still references it. Restored docs/images/crewai-otel-export.png from PR #3673; it was deleted in PR #4908 but v1.10.0 / v1.10.1 snapshots still reference it. Restoring instead of editing the snapshots preserves historical rendering fidelity and validates the new append-only rule retroactively. Tests: - lib/devtools/tests/test_docs_versioning.py covers the freeze: file copy, openapi rewrite, version insertion, default demotion, redirect upserts, per-section redirect rewriting, idempotency, and invalid inputs. Verified locally with mintlify broken-links: 0 broken links across the full site (Edge + 16 frozen versions, 4 locales). AGENTS.md (repo root) is the contributor guide for the new model; RELEASING.md is the release-cut runbook; README's Contribution section links to both. Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
Lucas Gomide
155
docs/edge/pt-BR/learn/using-annotations.mdx
Normal file
155
docs/edge/pt-BR/learn/using-annotations.mdx
Normal file
@@ -0,0 +1,155 @@
|
||||
---
|
||||
title: "Usando Anotações no crew.py"
|
||||
description: "Aprenda como usar anotações para estruturar corretamente agentes, tarefas e componentes no CrewAI"
|
||||
icon: "at"
|
||||
mode: "wide"
|
||||
---
|
||||
|
||||
Este guia explica como utilizar anotações para referenciar corretamente **agentes**, **tarefas** e outros componentes em um arquivo `crew.py` clássico.
|
||||
|
||||
<Note>
|
||||
Novos projetos criados com `crewai create crew <name>` são JSON-first e usam `crew.jsonc` com `agents/*.jsonc`. Use este guia ao trabalhar em um projeto clássico criado com `crewai create crew <name> --classic`, ao migrar um projeto Python/YAML existente ou quando precisar de controle via decorators em Python.
|
||||
</Note>
|
||||
|
||||
## Introdução
|
||||
|
||||
As anotações no framework CrewAI são utilizadas para decorar classes e métodos, fornecendo metadados e funcionalidades para diversos componentes do seu crew. Em projetos clássicos Python/YAML, elas organizam o código que carrega `config/agents.yaml`, `config/tasks.yaml` e retorna o objeto `Crew`.
|
||||
|
||||
## Anotações Disponíveis
|
||||
|
||||
O framework CrewAI fornece as seguintes anotações:
|
||||
|
||||
- `@CrewBase`: Usada para decorar a classe principal do crew.
|
||||
- `@agent`: Decora métodos que definem e retornam objetos Agent.
|
||||
- `@task`: Decora métodos que definem e retornam objetos Task.
|
||||
- `@crew`: Decora o método que cria e retorna o objeto Crew.
|
||||
- `@llm`: Decora métodos que inicializam e retornam objetos Language Model.
|
||||
- `@tool`: Decora métodos que inicializam e retornam objetos Tool.
|
||||
- `@callback`: Utilizada para definir métodos de callback.
|
||||
- `@output_json`: Utilizada para métodos que retornam dados em JSON.
|
||||
- `@output_pydantic`: Utilizada para métodos que retornam modelos Pydantic.
|
||||
- `@cache_handler`: Utilizada para definição de métodos de manipulação de cache.
|
||||
|
||||
## Exemplos de Uso
|
||||
|
||||
Vamos passar por exemplos de como utilizar essas anotações:
|
||||
|
||||
### 1. Classe Base do Crew
|
||||
|
||||
```python
|
||||
@CrewBase
|
||||
class LinkedinProfileCrew():
|
||||
"""LinkedinProfile crew"""
|
||||
agents_config = 'config/agents.yaml'
|
||||
tasks_config = 'config/tasks.yaml'
|
||||
```
|
||||
|
||||
A anotação `@CrewBase` é usada para decorar a classe principal do crew. Esta classe geralmente contém as configurações e métodos para criação de agentes, tarefas e do próprio crew.
|
||||
|
||||
<Tip>
|
||||
`@CrewBase` faz bem mais do que registrar a classe:
|
||||
|
||||
- **Inicialização de configuração:** busca `agents_config` e `tasks_config` (padrões `config/agents.yaml` e `config/tasks.yaml`) ao lado do arquivo da classe, carrega esses YAMLs na inicialização e utiliza dicionários vazios quando os arquivos não existem.
|
||||
- **Orquestração de decoradores:** mantém versões memoizadas dos métodos marcados com `@agent`, `@task`, `@before_kickoff` e `@after_kickoff` para que sejam instanciados uma única vez por crew e respeitem a ordem de declaração.
|
||||
- **Encadeamento de hooks:** conecta automaticamente os hooks preservados ao objeto `Crew` retornado pelo método `@crew`, garantindo que executem antes e depois de `.kickoff()`.
|
||||
- **Integração MCP:** quando a classe define `mcp_server_params`, `get_mcp_tools()` cria sob demanda um adaptador MCP, carrega as ferramentas declaradas e um hook interno pós-kickoff encerra o adaptador. Consulte a [visão geral de MCP](/pt-BR/mcp/overview) para detalhes de configuração.
|
||||
</Tip>
|
||||
|
||||
### 2. Definição de Tool
|
||||
|
||||
```python
|
||||
@tool
|
||||
def myLinkedInProfileTool(self):
|
||||
return LinkedInProfileTool()
|
||||
```
|
||||
|
||||
A anotação `@tool` é usada para decorar métodos que retornam objetos tool. Essas ferramentas podem ser usadas por agentes para executar tarefas específicas.
|
||||
|
||||
### 3. Definição de LLM
|
||||
|
||||
```python
|
||||
@llm
|
||||
def groq_llm(self):
|
||||
api_key = os.getenv('api_key')
|
||||
return ChatGroq(api_key=api_key, temperature=0, model_name="mixtral-8x7b-32768")
|
||||
```
|
||||
|
||||
A anotação `@llm` é usada para decorar métodos que inicializam e retornam objetos Language Model. Esses LLMs são utilizados pelos agentes para tarefas de processamento de linguagem natural.
|
||||
|
||||
### 4. Definição de Agente
|
||||
|
||||
```python
|
||||
@agent
|
||||
def researcher(self) -> Agent:
|
||||
return Agent(
|
||||
config=self.agents_config['researcher']
|
||||
)
|
||||
```
|
||||
|
||||
A anotação `@agent` é usada para decorar métodos que definem e retornam objetos Agent.
|
||||
|
||||
### 5. Definição de Tarefa
|
||||
|
||||
```python
|
||||
@task
|
||||
def research_task(self) -> Task:
|
||||
return Task(
|
||||
config=self.tasks_config['research_linkedin_task'],
|
||||
agent=self.researcher()
|
||||
)
|
||||
```
|
||||
|
||||
A anotação `@task` é usada para decorar métodos que definem e retornam objetos Task. Esses métodos especificam a configuração da tarefa e o agente responsável por ela.
|
||||
|
||||
### 6. Criação do Crew
|
||||
|
||||
```python
|
||||
@crew
|
||||
def crew(self) -> Crew:
|
||||
"""Creates the LinkedinProfile crew"""
|
||||
return Crew(
|
||||
agents=self.agents,
|
||||
tasks=self.tasks,
|
||||
process=Process.sequential,
|
||||
verbose=True
|
||||
)
|
||||
```
|
||||
|
||||
A anotação `@crew` é usada para decorar o método que cria e retorna o objeto `Crew`. Este método reúne todos os componentes (agentes e tarefas) em um crew funcional.
|
||||
|
||||
## Configuração YAML Clássica
|
||||
|
||||
Em projetos clássicos, as configurações dos agentes geralmente são armazenadas em um arquivo YAML. Veja um exemplo de como o arquivo `agents.yaml` pode ser estruturado para o agente researcher:
|
||||
|
||||
```yaml
|
||||
researcher:
|
||||
role: >
|
||||
LinkedIn Profile Senior Data Researcher
|
||||
goal: >
|
||||
Uncover detailed LinkedIn profiles based on provided name {name} and domain {domain}
|
||||
Generate a Dall-E image based on domain {domain}
|
||||
backstory: >
|
||||
You're a seasoned researcher with a knack for uncovering the most relevant LinkedIn profiles.
|
||||
Known for your ability to navigate LinkedIn efficiently, you excel at gathering and presenting
|
||||
professional information clearly and concisely.
|
||||
allow_delegation: False
|
||||
verbose: True
|
||||
llm: groq_llm
|
||||
tools:
|
||||
- myLinkedInProfileTool
|
||||
- mySerperDevTool
|
||||
- myDallETool
|
||||
```
|
||||
|
||||
Esta configuração YAML corresponde ao agente researcher definido na classe `LinkedinProfileCrew`. A configuração especifica o papel do agente, objetivo, contexto e outras propriedades, como o LLM e as tools que ele utiliza.
|
||||
|
||||
Repare como os campos `llm` e `tools` no arquivo YAML correspondem aos métodos decorados com `@llm` e `@tool` na classe Python.
|
||||
|
||||
## Boas Práticas
|
||||
|
||||
- **Nomenclatura Consistente**: Utilize nomenclatura clara e consistente para seus métodos. Por exemplo, métodos de agentes podem ser nomeados de acordo com suas funções (ex: researcher, reporting_analyst).
|
||||
- **Variáveis de Ambiente**: Utilize variáveis de ambiente para informações sensíveis como chaves de API.
|
||||
- **Flexibilidade**: Estruture seu crew de forma flexível, permitindo fácil adição ou remoção de agentes e tarefas.
|
||||
- **Correspondência YAML-Código**: Em projetos clássicos, assegure que os nomes e estruturas nos arquivos YAML correspondam corretamente aos métodos decorados em seu código Python.
|
||||
|
||||
Seguindo essas orientações e utilizando corretamente as anotações, você conseguirá manter crews clássicos bem estruturados. Para novas crews, prefira a estrutura JSON-first em [Crews](/pt-BR/concepts/crews).
|
||||
Reference in New Issue
Block a user