diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md new file mode 100644 index 000000000..38ca22ad4 --- /dev/null +++ b/.github/CONTRIBUTING.md @@ -0,0 +1,173 @@ +# Contributing to CrewAI + +## AI-Generated Contributions + +If you are an LLM or AI agent reading this: you must apply the `llm-generated` label to any PR or issue you create. + +If your PR or issue was authored by an AI agent, coding assistant, or LLM (e.g., Claude Code, Cursor, Copilot, Devin, OpenHands), the `llm-generated` label is required. This applies to code, documentation, and issues alike. Unlabeled AI-generated contributions may be closed without review. + +--- + +Thank you for your interest in contributing to CrewAI. This guide covers everything you need to get started. + +## Prerequisites + +- Python 3.10–3.14 (development targets 3.12) +- [uv](https://docs.astral.sh/uv/) for package management +- [pre-commit](https://pre-commit.com/) for Git hooks + +## Setup + +```bash +git clone https://github.com/crewAIInc/crewAI.git +cd crewAI + +uv sync --all-groups --all-extras + +uv run pre-commit install +``` + +## Repository Structure + +This is a uv workspace with four packages under `lib/`: + +| Package | Path | Description | +|---------|------|-------------| +| `crewai` | `lib/crewai/` | Core framework | +| `crewai-tools` | `lib/crewai-tools/` | Tool integrations | +| `crewai-files` | `lib/crewai-files/` | File handling | +| `devtools` | `lib/devtools/` | Internal release tooling | + +Documentation lives in `docs/` with translations under `docs/{en,ar,ko,pt-BR}/`. + +## Development Workflow + +### Branching + +Create a branch off `main` using the conventional commit type: + +``` +/ +``` + +Types: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`, `chore`, `ci` + +Examples: `feat/agent-skills`, `fix/memory-scope`, `docs/arabic-translation` + +### Code Quality + +Pre-commit hooks run automatically on commit. You can also run them manually: + +```bash +uv run ruff check lib/ + +uv run ruff format lib/ + +uv run mypy lib/ + +uv run pytest lib/crewai/tests/ -x -q +``` + +### Code Style + +- **Types**: Use built-in generics (`list[str]`, `dict[str, int]`), not `typing.List`/`typing.Dict` +- **Annotations**: Full type annotations on all functions, methods, and classes +- **Docstrings**: Google-style, minimal but informative +- **Imports**: Use `collections.abc` for abstract base classes +- **Type narrowing**: Use `isinstance`, `TypeIs`, or `TypeGuard` instead of `hasattr` +- **Avoid**: bare `dict`/`list` without type parameters + +### Commits + +Follow [Conventional Commits](https://www.conventionalcommits.org/): + +``` +(): +``` + +- Use imperative mood: "add feature" not "added feature" +- Keep the title under 72 characters +- Only add a body if it provides additional context beyond the title +- Do not use `--no-verify` to skip hooks + +Examples: +``` +feat(memory): add lancedb storage backend +fix(agents): resolve deadlock in concurrent execution +chore(deps): bump pydantic to 2.11 +``` + +### Pull Requests + +- One logical change per PR +- Keep PRs focused — avoid bundling unrelated changes +- PRs over 500 lines are labeled `size/XL` automatically +- Title must follow the same conventional commit format +- Link related issues where applicable + +## Testing + +```bash +# Run all tests +uv run pytest lib/crewai/tests/ -x -q + +# Run a specific test file +uv run pytest lib/crewai/tests/agents/test_agent.py -x -q + +# Run a specific test +uv run pytest lib/crewai/tests/agents/test_agent.py::test_agent_creation -x -q + +# Run crewai-tools tests +uv run pytest lib/crewai-tools/tests/ -x -q +``` + +## Type Checking + +The project enforces strict mypy across all packages: + +```bash +# Check everything +uv run mypy lib/ + +# Check a specific package +uv run mypy lib/crewai/src/crewai/ +``` + +CI runs mypy on Python 3.10, 3.11, 3.12, and 3.13 for every PR. + +## Documentation + +Docs use [Mintlify](https://mintlify.com/) and live in `docs/`. The site is configured via `docs/docs.json`. + +Supported languages: English (`en`), Arabic (`ar`), Korean (`ko`), Brazilian Portuguese (`pt-BR`). + +When adding or modifying documentation: +- Edit the English version in `docs/en/` first +- Update translations in `docs/{ar,ko,pt-BR}/` to maintain parity +- Keep all MDX/JSX syntax, code blocks, and URLs unchanged in translations +- Update `docs/docs.json` navigation if adding new pages + +## Dependency Management + +```bash +# Add a runtime dependency to crewai +uv add --package crewai + +# Add a dev dependency to the workspace +uv add --dev + +# Sync after changes +uv sync +``` + +Do not use `pip` directly. + +## Reporting Issues + +Use the [GitHub issue templates](https://github.com/crewAIInc/crewAI/issues/new/choose): +- **Bug Report**: For unexpected behavior +- **Feature Request**: For new functionality + +## License + +By contributing, you agree that your contributions will be licensed under the [MIT License](LICENSE). diff --git a/.github/security.md b/.github/security.md index 287735d66..3b2c115f3 100644 --- a/.github/security.md +++ b/.github/security.md @@ -1,50 +1,12 @@ ## CrewAI Security Policy -We are committed to protecting the confidentiality, integrity, and availability of the CrewAI ecosystem. This policy explains how to report potential vulnerabilities and what you can expect from us when you do. - -### Scope - -We welcome reports for vulnerabilities that could impact: - -- CrewAI-maintained source code and repositories -- CrewAI-operated infrastructure and services -- Official CrewAI releases, packages, and distributions - -Issues affecting clearly unaffiliated third-party services or user-generated content are out of scope, unless you can demonstrate a direct impact on CrewAI systems or customers. +We are committed to protecting the confidentiality, integrity, and availability of the +CrewAI ecosystem. ### How to Report -- **Please do not** disclose vulnerabilities via public GitHub issues, pull requests, or social media. -- Email detailed reports to **security@crewai.com** with the subject line `Security Report`. -- If you need to share large files or sensitive artifacts, mention it in your email and we will coordinate a secure transfer method. +Please submit reports to **crewai-vdp-ess@submit.bugcrowd.com** -### What to Include - -Providing comprehensive information enables us to validate the issue quickly: - -- **Vulnerability overview** — a concise description and classification (e.g., RCE, privilege escalation) -- **Affected components** — repository, branch, tag, or deployed service along with relevant file paths or endpoints -- **Reproduction steps** — detailed, step-by-step instructions; include logs, screenshots, or screen recordings when helpful -- **Proof-of-concept** — exploit details or code that demonstrates the impact (if available) -- **Impact analysis** — severity assessment, potential exploitation scenarios, and any prerequisites or special configurations - -### Our Commitment - -- **Acknowledgement:** We aim to acknowledge your report within two business days. -- **Communication:** We will keep you informed about triage results, remediation progress, and planned release timelines. -- **Resolution:** Confirmed vulnerabilities will be prioritized based on severity and fixed as quickly as possible. -- **Recognition:** We currently do not run a bug bounty program; any rewards or recognition are issued at CrewAI's discretion. - -### Coordinated Disclosure - -We ask that you allow us a reasonable window to investigate and remediate confirmed issues before any public disclosure. We will coordinate publication timelines with you whenever possible. - -### Safe Harbor - -We will not pursue or support legal action against individuals who, in good faith: - -- Follow this policy and refrain from violating any applicable laws -- Avoid privacy violations, data destruction, or service disruption -- Limit testing to systems in scope and respect rate limits and terms of service - -If you are unsure whether your testing is covered, please contact us at **security@crewai.com** before proceeding. +- **Please do not** disclose vulnerabilities via public GitHub issues, pull requests, + or social media +- Reports submitted via channels other than this Bugcrowd submission email will not be reviewed and will be dismissed diff --git a/.github/workflows/build-uv-cache.yml b/.github/workflows/build-uv-cache.yml index 3e5028eb7..06835d14c 100644 --- a/.github/workflows/build-uv-cache.yml +++ b/.github/workflows/build-uv-cache.yml @@ -28,7 +28,7 @@ jobs: - name: Install uv uses: astral-sh/setup-uv@v6 with: - version: "0.8.4" + version: "0.11.3" python-version: ${{ matrix.python-version }} enable-cache: false diff --git a/.github/workflows/docs-broken-links.yml b/.github/workflows/docs-broken-links.yml index baf2a6ea7..08e2ee19b 100644 --- a/.github/workflows/docs-broken-links.yml +++ b/.github/workflows/docs-broken-links.yml @@ -23,7 +23,7 @@ jobs: - name: Set up Node uses: actions/setup-node@v4 with: - node-version: "latest" + node-version: "22" - name: Install Mintlify CLI run: npm i -g mintlify diff --git a/.github/workflows/generate-tool-specs.yml b/.github/workflows/generate-tool-specs.yml index aa3c1bd5d..717135938 100644 --- a/.github/workflows/generate-tool-specs.yml +++ b/.github/workflows/generate-tool-specs.yml @@ -35,7 +35,7 @@ jobs: - name: Install uv uses: astral-sh/setup-uv@v6 with: - version: "0.8.4" + version: "0.11.3" python-version: "3.12" enable-cache: true diff --git a/.github/workflows/linter.yml b/.github/workflows/linter.yml index ae26c4209..b62b0eba5 100644 --- a/.github/workflows/linter.yml +++ b/.github/workflows/linter.yml @@ -6,17 +6,27 @@ permissions: contents: read jobs: - lint: + changes: + name: Detect changes runs-on: ubuntu-latest - env: - TARGET_BRANCH: ${{ github.event.pull_request.base.ref }} + outputs: + code: ${{ steps.filter.outputs.code }} steps: - uses: actions/checkout@v4 + - uses: dorny/paths-filter@v3 + id: filter with: - fetch-depth: 0 + filters: | + code: + - '!docs/**' + - '!**/*.md' - - name: Fetch Target Branch - run: git fetch origin $TARGET_BRANCH --depth=1 + lint-run: + needs: changes + if: needs.changes.outputs.code == 'true' + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 - name: Restore global uv cache id: cache-restore @@ -33,30 +43,18 @@ jobs: - name: Install uv uses: astral-sh/setup-uv@v6 with: - version: "0.8.4" + version: "0.11.3" python-version: "3.11" enable-cache: false - name: Install dependencies run: uv sync --all-groups --all-extras --no-install-project - - name: Get Changed Python Files - id: changed-files - run: | - merge_base=$(git merge-base origin/"$TARGET_BRANCH" HEAD) - changed_files=$(git diff --name-only --diff-filter=ACMRTUB "$merge_base" | grep '\.py$' || true) - echo "files<> $GITHUB_OUTPUT - echo "$changed_files" >> $GITHUB_OUTPUT - echo "EOF" >> $GITHUB_OUTPUT + - name: Ruff check + run: uv run ruff check lib/ - - name: Run Ruff on Changed Files - if: ${{ steps.changed-files.outputs.files != '' }} - run: | - echo "${{ steps.changed-files.outputs.files }}" \ - | tr ' ' '\n' \ - | grep -v 'src/crewai/cli/templates/' \ - | grep -v '/tests/' \ - | xargs -I{} uv run ruff check "{}" + - name: Ruff format + run: uv run ruff format --check lib/ - name: Save uv caches if: steps.cache-restore.outputs.cache-hit != 'true' @@ -67,3 +65,23 @@ jobs: ~/.local/share/uv .venv key: uv-main-py3.11-${{ hashFiles('uv.lock') }} + + # Summary job to provide single status for branch protection + lint: + name: lint + runs-on: ubuntu-latest + needs: [changes, lint-run] + if: always() + steps: + - name: Check results + run: | + if [ "${{ needs.changes.outputs.code }}" != "true" ]; then + echo "Docs-only change, skipping lint" + exit 0 + fi + if [ "${{ needs.lint-run.result }}" == "success" ]; then + echo "Lint passed" + else + echo "Lint failed" + exit 1 + fi diff --git a/.github/workflows/nightly.yml b/.github/workflows/nightly.yml index 309014dfe..2cfadad15 100644 --- a/.github/workflows/nightly.yml +++ b/.github/workflows/nightly.yml @@ -95,7 +95,7 @@ jobs: - name: Install uv uses: astral-sh/setup-uv@v6 with: - version: "0.8.4" + version: "0.11.3" python-version: "3.12" enable-cache: false diff --git a/.github/workflows/pr-size.yml b/.github/workflows/pr-size.yml new file mode 100644 index 000000000..5653dcc09 --- /dev/null +++ b/.github/workflows/pr-size.yml @@ -0,0 +1,32 @@ +name: PR Size Check + +on: + pull_request: + types: [opened, synchronize, reopened] + +jobs: + pr-size: + runs-on: ubuntu-latest + permissions: + pull-requests: write + steps: + - uses: codelytv/pr-size-labeler@v1 + with: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + xs_label: "size/XS" + xs_max_size: 25 + s_label: "size/S" + s_max_size: 100 + m_label: "size/M" + m_max_size: 250 + l_label: "size/L" + l_max_size: 500 + xl_label: "size/XL" + fail_if_xl: false + files_to_ignore: | + uv.lock + *.lock + lib/crewai/src/crewai/cli/templates/** + **/*.json + **/test_durations/** + **/cassettes/** \ No newline at end of file diff --git a/.github/workflows/pr-title.yml b/.github/workflows/pr-title.yml new file mode 100644 index 000000000..00dafe5a5 --- /dev/null +++ b/.github/workflows/pr-title.yml @@ -0,0 +1,41 @@ +name: PR Title Check + +on: + pull_request: + types: [opened, edited, synchronize, reopened] + +permissions: + contents: read + pull-requests: read + +jobs: + pr-title: + runs-on: ubuntu-latest + steps: + - uses: amannn/action-semantic-pull-request@v5 + continue-on-error: true + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + with: + types: | + feat + fix + refactor + perf + test + docs + chore + ci + style + revert + requireScope: false + subjectPattern: ^[a-z].+[^.]$ + subjectPatternError: > + The PR title "{title}" does not follow conventional commit format. + + Expected: (): + + Examples: + feat(memory): add lancedb storage backend + fix(agents): resolve deadlock in concurrent execution + chore(deps): bump pydantic to 2.11.9 diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.yml index 5097231b9..f2b1bc1b0 100644 --- a/.github/workflows/publish.yml +++ b/.github/workflows/publish.yml @@ -65,7 +65,7 @@ jobs: - name: Install uv uses: astral-sh/setup-uv@v6 with: - version: "0.8.4" + version: "0.11.3" python-version: "3.12" enable-cache: false diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index 6d8054ff4..71a7b801a 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -6,8 +6,25 @@ permissions: contents: read jobs: - tests: + changes: + name: Detect changes + runs-on: ubuntu-latest + outputs: + code: ${{ steps.filter.outputs.code }} + steps: + - uses: actions/checkout@v4 + - uses: dorny/paths-filter@v3 + id: filter + with: + filters: | + code: + - '!docs/**' + - '!**/*.md' + + tests-matrix: name: tests (${{ matrix.python-version }}) + needs: changes + if: needs.changes.outputs.code == 'true' runs-on: ubuntu-latest timeout-minutes: 15 strategy: @@ -36,7 +53,7 @@ jobs: - name: Install uv uses: astral-sh/setup-uv@v6 with: - version: "0.8.4" + version: "0.11.3" python-version: ${{ matrix.python-version }} enable-cache: false @@ -98,3 +115,23 @@ jobs: ~/.local/share/uv .venv key: uv-main-py${{ matrix.python-version }}-${{ hashFiles('uv.lock') }} + + # Summary job to provide single status for branch protection + tests: + name: tests + runs-on: ubuntu-latest + needs: [changes, tests-matrix] + if: always() + steps: + - name: Check results + run: | + if [ "${{ needs.changes.outputs.code }}" != "true" ]; then + echo "Docs-only change, skipping tests" + exit 0 + fi + if [ "${{ needs.tests-matrix.result }}" == "success" ]; then + echo "All tests passed" + else + echo "Tests failed" + exit 1 + fi diff --git a/.github/workflows/type-checker.yml b/.github/workflows/type-checker.yml index 03a5841a0..8d88d4b6a 100644 --- a/.github/workflows/type-checker.yml +++ b/.github/workflows/type-checker.yml @@ -6,8 +6,25 @@ permissions: contents: read jobs: + changes: + name: Detect changes + runs-on: ubuntu-latest + outputs: + code: ${{ steps.filter.outputs.code }} + steps: + - uses: actions/checkout@v4 + - uses: dorny/paths-filter@v3 + id: filter + with: + filters: | + code: + - '!docs/**' + - '!**/*.md' + type-checker-matrix: name: type-checker (${{ matrix.python-version }}) + needs: changes + if: needs.changes.outputs.code == 'true' runs-on: ubuntu-latest strategy: fail-fast: false @@ -17,8 +34,6 @@ jobs: steps: - name: Checkout code uses: actions/checkout@v4 - with: - fetch-depth: 0 # Fetch all history for proper diff - name: Restore global uv cache id: cache-restore @@ -35,44 +50,15 @@ jobs: - name: Install uv uses: astral-sh/setup-uv@v6 with: - version: "0.8.4" + version: "0.11.3" python-version: ${{ matrix.python-version }} enable-cache: false - name: Install dependencies run: uv sync --all-groups --all-extras - - name: Get changed Python files - id: changed-files - run: | - # Get the list of changed Python files compared to the base branch - echo "Fetching changed files..." - git diff --name-only --diff-filter=ACMRT origin/${{ github.base_ref }}...HEAD -- '*.py' > changed_files.txt - - # Filter for files in src/ directory only (excluding tests/) - grep -E "^src/" changed_files.txt > filtered_changed_files.txt || true - - # Check if there are any changed files - if [ -s filtered_changed_files.txt ]; then - echo "Changed Python files in src/:" - cat filtered_changed_files.txt - echo "has_changes=true" >> $GITHUB_OUTPUT - # Convert newlines to spaces for mypy command - echo "files=$(cat filtered_changed_files.txt | tr '\n' ' ')" >> $GITHUB_OUTPUT - else - echo "No Python files changed in src/" - echo "has_changes=false" >> $GITHUB_OUTPUT - fi - - - name: Run type checks on changed files - if: steps.changed-files.outputs.has_changes == 'true' - run: | - echo "Running mypy on changed files with Python ${{ matrix.python-version }}..." - uv run mypy ${{ steps.changed-files.outputs.files }} - - - name: No files to check - if: steps.changed-files.outputs.has_changes == 'false' - run: echo "No Python files in src/ were modified - skipping type checks" + - name: Run type checks + run: uv run mypy lib/ - name: Save uv caches if: steps.cache-restore.outputs.cache-hit != 'true' @@ -88,14 +74,18 @@ jobs: type-checker: name: type-checker runs-on: ubuntu-latest - needs: type-checker-matrix + needs: [changes, type-checker-matrix] if: always() steps: - - name: Check matrix results + - name: Check results run: | - if [ "${{ needs.type-checker-matrix.result }}" == "success" ] || [ "${{ needs.type-checker-matrix.result }}" == "skipped" ]; then - echo "✅ All type checks passed" + if [ "${{ needs.changes.outputs.code }}" != "true" ]; then + echo "Docs-only change, skipping type checks" + exit 0 + fi + if [ "${{ needs.type-checker-matrix.result }}" == "success" ]; then + echo "All type checks passed" else - echo "❌ Type checks failed" + echo "Type checks failed" exit 1 fi diff --git a/.github/workflows/update-test-durations.yml b/.github/workflows/update-test-durations.yml index 13f1ecd69..4084fb64d 100644 --- a/.github/workflows/update-test-durations.yml +++ b/.github/workflows/update-test-durations.yml @@ -40,7 +40,7 @@ jobs: - name: Install uv uses: astral-sh/setup-uv@v6 with: - version: "0.8.4" + version: "0.11.3" python-version: ${{ matrix.python-version }} enable-cache: false diff --git a/.github/workflows/vulnerability-scan.yml b/.github/workflows/vulnerability-scan.yml new file mode 100644 index 000000000..90b289d79 --- /dev/null +++ b/.github/workflows/vulnerability-scan.yml @@ -0,0 +1,105 @@ +name: Vulnerability Scan + +on: + pull_request: + push: + branches: [main] + schedule: + # Run weekly on Monday at 9:00 UTC + - cron: '0 9 * * 1' + +permissions: + contents: read + +jobs: + pip-audit: + name: pip-audit + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Restore global uv cache + id: cache-restore + uses: actions/cache/restore@v4 + with: + path: | + ~/.cache/uv + ~/.local/share/uv + .venv + key: uv-main-py3.11-${{ hashFiles('uv.lock') }} + restore-keys: | + uv-main-py3.11- + + - name: Install uv + uses: astral-sh/setup-uv@v6 + with: + version: "0.11.3" + python-version: "3.11" + enable-cache: false + + - name: Install dependencies + run: uv sync --all-groups --all-extras --no-install-project + + - name: Install pip-audit + run: uv pip install pip-audit + + - name: Run pip-audit + run: | + uv run pip-audit --desc --aliases --skip-editable --format json --output pip-audit-report.json \ + --ignore-vuln CVE-2025-69872 \ + --ignore-vuln CVE-2026-25645 \ + --ignore-vuln CVE-2026-27448 \ + --ignore-vuln CVE-2026-27459 \ + --ignore-vuln PYSEC-2023-235 + # Ignored CVEs: + # CVE-2025-69872 - diskcache 5.6.3: no fix available (latest version) + # CVE-2026-25645 - requests 2.32.5: fix requires 2.33.0, blocked by crewai-tools ~=2.32.5 pin + # CVE-2026-27448 - pyopenssl 25.3.0: fix requires 26.0.0, blocked by snowflake-connector-python <26.0.0 pin + # CVE-2026-27459 - pyopenssl 25.3.0: same as above + # PYSEC-2023-235 - couchbase: fixed in 4.6.0 (already upgraded), advisory not yet updated + continue-on-error: true + + - name: Display results + if: always() + run: | + if [ -f pip-audit-report.json ]; then + echo "## pip-audit Results" >> $GITHUB_STEP_SUMMARY + echo '```json' >> $GITHUB_STEP_SUMMARY + cat pip-audit-report.json | python3 -m json.tool >> $GITHUB_STEP_SUMMARY + echo '```' >> $GITHUB_STEP_SUMMARY + # Fail if vulnerabilities found + python3 -c " + import json, sys + with open('pip-audit-report.json') as f: + data = json.load(f) + vulns = [d for d in data.get('dependencies', []) if d.get('vulns')] + if vulns: + print(f'::error::Found vulnerabilities in {len(vulns)} package(s)') + for v in vulns: + for vuln in v['vulns']: + print(f' - {v[\"name\"]}=={v[\"version\"]}: {vuln[\"id\"]}') + sys.exit(1) + print('No known vulnerabilities found') + " + else + echo "::error::pip-audit failed to produce a report. Check the pip-audit step logs." + exit 1 + fi + + - name: Upload pip-audit report + if: always() + uses: actions/upload-artifact@v4 + with: + name: pip-audit-report + path: pip-audit-report.json + + - name: Save uv caches + if: steps.cache-restore.outputs.cache-hit != 'true' + uses: actions/cache/save@v4 + with: + path: | + ~/.cache/uv + ~/.local/share/uv + .venv + key: uv-main-py3.11-${{ hashFiles('uv.lock') }} + diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index defe87b5c..d704c83b1 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -21,7 +21,7 @@ repos: types: [python] exclude: ^(lib/crewai/src/crewai/cli/templates/|lib/crewai/tests/|lib/crewai-tools/tests/|lib/crewai-files/tests/) - repo: https://github.com/astral-sh/uv-pre-commit - rev: 0.9.3 + rev: 0.11.3 hooks: - id: uv-lock - repo: https://github.com/commitizen-tools/commitizen diff --git a/conftest.py b/conftest.py index 9b2c7c5c4..09852767e 100644 --- a/conftest.py +++ b/conftest.py @@ -43,6 +43,35 @@ def _patched_make_vcr_request(httpx_request: Any, **kwargs: Any) -> Any: httpx_stubs._make_vcr_request = _patched_make_vcr_request +# Patch the response-side of VCR to fix httpx.ResponseNotRead errors. +# VCR's _from_serialized_response mocks httpx.Response.read(), which prevents +# the response's internal _content attribute from being properly initialized. +# When OpenAI's client (using with_raw_response) accesses response.content, +# httpx raises ResponseNotRead because read() was never actually called. +# This patch ensures _content is explicitly set after response creation. +_original_from_serialized_response = getattr( + httpx_stubs, "_from_serialized_response", None +) + +if _original_from_serialized_response is not None: + + def _patched_from_serialized_response( + request: Any, serialized_response: Any, history: Any = None + ) -> Any: + """Patched version that ensures response._content is properly set.""" + response = _original_from_serialized_response(request, serialized_response, history) + # Explicitly set _content to avoid ResponseNotRead errors + # The content was passed to the constructor but the mocked read() prevents + # proper initialization of the internal state + body_content = serialized_response.get("body", {}).get("string", b"") + if isinstance(body_content, str): + body_content = body_content.encode("utf-8") + response._content = body_content + return response + + httpx_stubs._from_serialized_response = _patched_from_serialized_response + + @pytest.fixture(autouse=True, scope="function") def cleanup_event_handlers() -> Generator[None, Any, None]: """Clean up event bus handlers after each test to prevent test pollution.""" diff --git a/docs/ar/api-reference/inputs.mdx b/docs/ar/api-reference/inputs.mdx new file mode 100644 index 000000000..1c8d2d562 --- /dev/null +++ b/docs/ar/api-reference/inputs.mdx @@ -0,0 +1,8 @@ +--- +title: "GET /inputs" +description: "الحصول على المدخلات المطلوبة لطاقمك" +openapi: "/enterprise-api.en.yaml GET /inputs" +mode: "wide" +--- + + diff --git a/docs/ar/api-reference/introduction.mdx b/docs/ar/api-reference/introduction.mdx new file mode 100644 index 000000000..1d368341c --- /dev/null +++ b/docs/ar/api-reference/introduction.mdx @@ -0,0 +1,135 @@ +--- +title: "مقدمة" +description: "المرجع الكامل لواجهة برمجة تطبيقات CrewAI AMP REST" +icon: "code" +mode: "wide" +--- + +# واجهة برمجة تطبيقات CrewAI AMP + +مرحبًا بك في مرجع واجهة برمجة تطبيقات CrewAI AMP. تتيح لك هذه الواجهة التفاعل برمجيًا مع الأطقم المنشورة، مما يمكّنك من دمجها مع تطبيقاتك وسير عملك وخدماتك. + +## البدء السريع + + + + انتقل إلى صفحة تفاصيل طاقمك في لوحة تحكم CrewAI AMP وانسخ رمز Bearer من علامة تبويب الحالة. + + + + استخدم نقطة النهاية `GET /inputs` لمعرفة المعاملات التي يتوقعها طاقمك. + + + + استدعِ `POST /kickoff` مع مدخلاتك لبدء تنفيذ الطاقم واستلام + `kickoff_id`. + + + + استخدم `GET /{kickoff_id}/status` للتحقق من حالة التنفيذ واسترجاع النتائج. + + + +## المصادقة + +تتطلب جميع طلبات API المصادقة باستخدام رمز Bearer. أدرج رمزك في ترويسة `Authorization`: + +```bash +curl -H "Authorization: Bearer YOUR_CREW_TOKEN" \ + https://your-crew-url.crewai.com/inputs +``` + +### أنواع الرموز + +| نوع الرمز | النطاق | حالة الاستخدام | +| :-------------------- | :------------------------ | :----------------------------------------------------------- | +| **Bearer Token** | وصول على مستوى المؤسسة | عمليات الطاقم الكاملة، مثالي للتكامل بين الخوادم | +| **User Bearer Token** | وصول محدد بالمستخدم | صلاحيات محدودة، مناسب للعمليات الخاصة بالمستخدم | + + + يمكنك العثور على كلا نوعي الرموز في علامة تبويب الحالة من صفحة تفاصيل طاقمك في + لوحة تحكم CrewAI AMP. + + +## عنوان URL الأساسي + +لكل طاقم منشور نقطة نهاية API فريدة خاصة به: + +``` +https://your-crew-name.crewai.com +``` + +استبدل `your-crew-name` بعنوان URL الفعلي لطاقمك من لوحة التحكم. + +## سير العمل النموذجي + +1. **الاكتشاف**: استدعِ `GET /inputs` لفهم ما يحتاجه طاقمك +2. **التنفيذ**: أرسل المدخلات عبر `POST /kickoff` لبدء المعالجة +3. **المراقبة**: استعلم عن `GET /{kickoff_id}/status` حتى الاكتمال +4. **النتائج**: استخرج المخرجات النهائية من الاستجابة المكتملة + +## معالجة الأخطاء + +تستخدم الواجهة أكواد حالة HTTP القياسية: + +| الكود | المعنى | +| ----- | :----------------------------------------- | +| `200` | نجاح | +| `400` | طلب غير صالح - تنسيق مدخلات غير صحيح | +| `401` | غير مصرّح - رمز bearer غير صالح | +| `404` | غير موجود - المورد غير موجود | +| `422` | خطأ في التحقق - مدخلات مطلوبة مفقودة | +| `500` | خطأ في الخادم - تواصل مع الدعم | + +## الاختبار التفاعلي + + + **لماذا لا يوجد زر "إرسال"؟** نظرًا لأن كل مستخدم CrewAI AMP لديه عنوان URL + فريد للطاقم، نستخدم **وضع المرجع** بدلاً من بيئة تفاعلية لتجنب + الالتباس. يوضح لك هذا بالضبط كيف يجب أن تبدو الطلبات بدون + أزرار إرسال غير فعالة. + + +تعرض لك كل صفحة نقطة نهاية: + +- **تنسيق الطلب الدقيق** مع جميع المعاملات +- **أمثلة الاستجابة** لحالات النجاح والخطأ +- **عينات الكود** بلغات متعددة (cURL، Python، JavaScript، إلخ) +- **أمثلة المصادقة** بتنسيق رمز Bearer الصحيح + +### **لاختبار واجهتك الفعلية:** + + + + انسخ أمثلة cURL واستبدل العنوان URL + الرمز بقيمك الحقيقية + + + استورد الأمثلة في أداة اختبار API المفضلة لديك + + + +**مثال على سير العمل:** + +1. **انسخ مثال cURL هذا** من أي صفحة نقطة نهاية +2. **استبدل `your-actual-crew-name.crewai.com`** بعنوان URL الحقيقي لطاقمك +3. **استبدل رمز Bearer** برمزك الحقيقي من لوحة التحكم +4. **نفّذ الطلب** في طرفيتك أو عميل API + +## هل تحتاج مساعدة؟ + + + + احصل على مساعدة في تكامل API واستكشاف الأخطاء وإصلاحها + + + إدارة أطقمك وعرض سجلات التنفيذ + + diff --git a/docs/ar/api-reference/kickoff.mdx b/docs/ar/api-reference/kickoff.mdx new file mode 100644 index 000000000..84f3e8128 --- /dev/null +++ b/docs/ar/api-reference/kickoff.mdx @@ -0,0 +1,8 @@ +--- +title: "POST /kickoff" +description: "بدء تنفيذ الطاقم" +openapi: "/enterprise-api.en.yaml POST /kickoff" +mode: "wide" +--- + + diff --git a/docs/ar/api-reference/resume.mdx b/docs/ar/api-reference/resume.mdx new file mode 100644 index 000000000..f66b8b4d1 --- /dev/null +++ b/docs/ar/api-reference/resume.mdx @@ -0,0 +1,6 @@ +--- +title: "POST /resume" +description: "استئناف تنفيذ الطاقم مع التغذية الراجعة البشرية" +openapi: "/enterprise-api.en.yaml POST /resume" +mode: "wide" +--- diff --git a/docs/ar/api-reference/status.mdx b/docs/ar/api-reference/status.mdx new file mode 100644 index 000000000..b57fd0091 --- /dev/null +++ b/docs/ar/api-reference/status.mdx @@ -0,0 +1,6 @@ +--- +title: "GET /{kickoff_id}/status" +description: "الحصول على حالة التنفيذ" +openapi: "/enterprise-api.en.yaml GET /{kickoff_id}/status" +mode: "wide" +--- diff --git a/docs/ar/changelog.mdx b/docs/ar/changelog.mdx new file mode 100644 index 000000000..177ac6142 --- /dev/null +++ b/docs/ar/changelog.mdx @@ -0,0 +1,814 @@ +--- +title: "سجل التغييرات" +description: "تحديثات المنتج والتحسينات وإصلاحات الأخطاء لـ CrewAI" +icon: "clock" +mode: "wide" +--- + + ## v1.14.2a1 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.2a1) + + ## ما الذي تغير + + ### إصلاحات الأخطاء + - إصلاح إصدار حدث flow_finished بعد استئناف HITL + - إصلاح إصدار التشفير إلى 46.0.7 لمعالجة CVE-2026-39892 + + ### إعادة هيكلة + - إعادة هيكلة لاستخدام I18N_DEFAULT المشترك + + ### الوثائق + - تحديث سجل التغييرات والإصدار لـ v1.14.1 + + ## المساهمون + + @greysonlalonde + + + + + ## v1.14.1 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.1) + + ## ما الذي تغير + + ### الميزات + - إضافة متصفح TUI لنقاط التفتيش غير المتزامنة + - إضافة دالة aclose()/close() ومدير سياق غير متزامن لمخرجات البث + + ### إصلاحات الأخطاء + - إصلاح التعبير النمطي لزيادة إصدار pyproject.toml + - تنظيف أسماء الأدوات في مرشحات زخرفة الخطاف + - إصلاح تسجيل معالجات نقاط التفتيش عند إنشاء CheckpointConfig + - رفع إصدار transformers إلى 5.5.0 لحل CVE-2026-1839 + - إزالة غلاف FilteredStream لـ stdout/stderr + + ### الوثائق + - تحديث سجل التغييرات والإصدار لـ v1.14.1rc1 + + ### إعادة الهيكلة + - استبدال القائمة المحظورة الثابتة باستبعاد حقل BaseTool الديناميكي في توليد المواصفات + - استبدال التعبير النمطي بـ tomlkit في واجهة سطر أوامر أدوات التطوير + - استخدام كائن PRINTER المشترك + - جعل BaseProvider نموذجاً أساسياً مع مميز نوع المزود + + ## المساهمون + + @greysonlalonde, @iris-clawd, @joaomdmoura, @lorenzejay + + + + + ## v1.14.1rc1 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.1rc1) + + ## ما الذي تغير + + ### الميزات + - إضافة متصفح TUI لنقطة التحقق غير المتزامنة + - إضافة aclose()/close() ومدير سياق غير متزامن لمخرجات البث + + ### إصلاحات الأخطاء + - إصلاح زيادة إصدارات pyproject.toml باستخدام التعبيرات العادية + - تنظيف أسماء الأدوات في مرشحات ديكور المكونات + - زيادة إصدار transformers إلى 5.5.0 لحل CVE-2026-1839 + - تسجيل معالجات نقطة التحقق عند إنشاء CheckpointConfig + + ### إعادة الهيكلة + - استبدال القائمة المحظورة الثابتة باستبعاد حقل BaseTool الديناميكي في توليد المواصفات + - استبدال التعبيرات العادية بـ tomlkit في واجهة سطر الأوامر devtools + - استخدام كائن PRINTER المشترك + - جعل BaseProvider نموذجًا أساسيًا مع مميز نوع المزود + - إزالة غلاف stdout/stderr لـ FilteredStream + - إزالة flow/config.py غير المستخدمة + + ### الوثائق + - تحديث سجل التغييرات والإصدار لـ v1.14.0 + + ## المساهمون + + @greysonlalonde, @iris-clawd, @joaomdmoura + + + + + ## v1.14.0 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.0) + + ## ما الذي تغير + + ### الميزات + - إضافة أوامر CLI لقائمة/معلومات نقاط التحقق + - إضافة guardrail_type و name لتمييز التتبع + - إضافة SqliteProvider لتخزين نقاط التحقق + - إضافة CheckpointConfig للتسجيل التلقائي لنقاط التحقق + - تنفيذ تسجيل حالة وقت التشغيل، نظام الأحداث، وإعادة هيكلة المنفذ + + ### إصلاحات الأخطاء + - إضافة حماية من SSRF وتجاوز المسار + - إضافة التحقق من المسار وعنوان URL لأدوات RAG + - استبعاد متجهات التضمين من تسلسل الذاكرة لتوفير الرموز + - التأكد من وجود دليل الإخراج قبل الكتابة في قالب التدفق + - رفع litellm إلى >=1.83.0 لمعالجة CVE-2026-35030 + - إزالة حقل فهرسة SEO الذي يتسبب في عرض الصفحة العربية بشكل غير صحيح + + ### الوثائق + - تحديث سجل التغييرات والإصدار لـ v1.14.0 + - تحديث أدلة البدء السريع والتثبيت لتحسين الوضوح + - إضافة قسم مزودي التخزين، تصدير JsonProvider + - إضافة دليل علامة AMP التدريبية + + ### إعادة الهيكلة + - تنظيف واجهة برمجة تطبيقات نقاط التحقق + - إزالة CodeInterpreterTool وإهمال معلمات تنفيذ الكود + + ## المساهمون + + @alex-clawd, @github-actions[bot], @greysonlalonde, @iris-clawd, @joaomdmoura, @lorenzejay, @lucasgomide + + + + + ## v1.14.0a4 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.0a4) + + ## ما الذي تغير + + ### الميزات + - إضافة guardrail_type و name لتمييز الآثار + - إضافة SqliteProvider لتخزين نقاط التحقق + - إضافة CheckpointConfig للتخزين التلقائي لنقاط التحقق + - تنفيذ نقاط التحقق لحالة التشغيل، نظام الأحداث، وإعادة هيكلة المنفذ + + ### إصلاحات الأخطاء + - استبعاد متجهات التضمين من تسلسل الذاكرة لتوفير الرموز + - رفع litellm إلى >=1.83.0 لمعالجة CVE-2026-35030 + + ### الوثائق + - تحديث أدلة البدء السريع والتثبيت لتحسين الوضوح + - إضافة قسم مقدمي التخزين وتصدير JsonProvider + + ### الأداء + - استخدام JSONB لعمود بيانات نقاط التحقق + + ### إعادة الهيكلة + - إزالة CodeInterpreterTool وإهمال معلمات تنفيذ الكود + + ## المساهمون + + @alex-clawd, @github-actions[bot], @greysonlalonde, @joaomdmoura, @lorenzejay, @lucasgomide + + + + + ## v1.14.0a3 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.0a3) + + ## ما الذي تغير + + ### الوثائق + - تحديث سجل التغييرات والإصدار لـ v1.14.0a2 + + ## المساهمون + + @joaomdmoura + + + + + ## v1.14.0a2 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.14.0a2) + + # ملاحظات الإصدار 1.14.0a2 + + ## التعليمات: + - ترجم جميع عناوين الأقسام والوصف بشكل طبيعي + - احتفظ بتنسيق markdown (##، ###، -، إلخ) كما هو + - احتفظ بجميع الأسماء الصحيحة، ومعرفات الشيفرة، وأسماء الفئات، والمصطلحات التقنية دون تغيير + (مثل "CrewAI"، "LiteAgent"، "ChromaDB"، "MCP"، "@username") + - احتفظ بقسم ## المساهمون وأسماء مستخدمي GitHub كما هي + - لا تضف أو تزيل أي محتوى، فقط ترجم + + ## المميزات الجديدة + - تمت إضافة دعم لـ "ChromaDB" لتحسين أداء قاعدة البيانات. + - تحسينات على "LiteAgent" لزيادة الكفاءة. + + ## الإصلاحات + - إصلاح مشكلة تتعلق بـ "MCP" التي كانت تؤدي إلى تعطل التطبيق. + - معالجة الأخطاء المتعلقة بواجهة المستخدم في "CrewAI". + + ## المساهمون + - @username1 + - @username2 + - @username3 + + + + + ## v1.13.0 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.13.0) + + ## ما الذي تغير + + ### الميزات + - إضافة نموذج RuntimeState RootModel لتوحيد تسلسل الحالة + - تعزيز مستمع الأحداث مع نطاقات جديدة للقياس عن أحداث المهارة والذاكرة + - إضافة امتداد A2UI مع دعم v0.8/v0.9، والمخططات، والوثائق + - إصدار بيانات استخدام الرموز في حدث LLMCallCompletedEvent + - تحديث تلقائي لمستودع اختبار النشر أثناء الإصدار + - تحسين مرونة الإصدار المؤسسي وتجربة المستخدم + + ### إصلاحات الأخطاء + - إضافة بيانات اعتماد مستودع الأدوات إلى تثبيت crewai + - إضافة بيانات اعتماد مستودع الأدوات إلى بناء uv في نشر الأدوات + - تمرير بيانات التعريف عبر الإعدادات بدلاً من معلمات الأدوات + - معالجة نماذج GPT-5.x التي لا تدعم معلمة API `stop` + - إضافة GPT-5 وسلسلة o إلى بادئات الرؤية متعددة الوسائط + - مسح ذاكرة التخزين المؤقت uv للحزم التي تم نشرها حديثًا في الإصدار المؤسسي + - تحديد lancedb أقل من 0.30.1 لضمان التوافق مع Windows + - إصلاح مستويات أذونات RBAC لتتناسب مع خيارات واجهة المستخدم الفعلية + - إصلاح عدم الدقة في قدرات الوكيل عبر جميع اللغات + + ### الوثائق + - إضافة فيديو توضيحي لمهارات وكيل البرمجة إلى صفحات البدء + - إضافة دليل شامل لتكوين SSO + - إضافة مصفوفة شاملة لأذونات RBAC ودليل النشر + - تحديث سجل التغييرات والإصدار إلى v1.13.0 + + ### الأداء + - تقليل الحمل الزائد للإطار باستخدام حافلة الأحداث الكسولة، وتخطي التتبع عند تعطيله + + ### إعادة الهيكلة + - تحويل Flow إلى Pydantic BaseModel + - تحويل فئات LLM إلى Pydantic BaseModel + - استبدال InstanceOf[T] بتعليقات نوع عادية + - إزالة دليل LLM الخاص بالطرف الثالث غير المستخدم + + ## المساهمون + + @alex-clawd, @dependabot[bot], @greysonlalonde, @iris-clawd, @joaomdmoura, @lorenzejay, @lucasgomide, @thiagomoretto + + + + + ## v1.13.0a7 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.13.0a7) + + ## ما الذي تغير + + ### الميزات + - إضافة امتداد A2UI مع دعم v0.8/v0.9، والمخططات، والوثائق + + ### إصلاحات الأخطاء + - إصلاح بادئات الرؤية متعددة الأنماط عن طريق إضافة GPT-5 وسلسلة o + + ### الوثائق + - تحديث سجل التغييرات والإصدار لـ v1.13.0a6 + + ## المساهمون + + @alex-clawd, @greysonlalonde, @joaomdmoura + + + + + ## v1.13.0a6 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.13.0a6) + + ## ما الذي تغير + + ### الوثائق + - إصلاح مستويات أذونات RBAC لتتوافق مع خيارات واجهة المستخدم الفعلية (#5210) + - تحديث سجل التغييرات والإصدار لـ v1.13.0a5 (#5200) + + ### الأداء + - تقليل عبء العمل على الإطار من خلال تنفيذ حافلة أحداث كسولة وتجاوز التتبع عند تعطيله (#5187) + + ## المساهمون + + @alex-clawd, @joaomdmoura, @lucasgomide + + + + + ## v1.13.0a5 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.13.0a5) + + ## ما الذي تغير + + ### الوثائق + - تحديث سجل التغييرات والإصدار لـ v1.13.0a4 + + ## المساهمون + + @greysonlalonde, @joaomdmoura + + + + + ## v1.13.0a4 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.13.0a4) + + ## ما الذي تغير + + ### الوثائق + - تحديث سجل التغييرات والإصدار لـ v1.13.0a3 + + ## المساهمون + + @greysonlalonde + + + + + ## v1.13.0a3 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.13.0a3) + + ## ما الذي تغير + + ### الميزات + - إصدار بيانات استخدام الرمز في LLMCallCompletedEvent + - استخراج ونشر بيانات الأداة إلى AMP + + ### إصلاح الأخطاء + - التعامل مع نماذج GPT-5.x التي لا تدعم معلمة API `stop` + + ### الوثائق + - إصلاح عدم الدقة في قدرات الوكيل عبر جميع اللغات + - إضافة نظرة عامة على قدرات الوكيل وتحسين وثائق المهارات + - إضافة دليل شامل لتكوين SSO + - تحديث سجل التغييرات والإصدار لـ v1.13.0rc1 + + ### إعادة الهيكلة + - تحويل Flow إلى Pydantic BaseModel + - تحويل فئات LLM إلى Pydantic BaseModel + - استبدال InstanceOf[T] بتعليقات نوع عادية + - إزالة الطرق غير المستخدمة + + ## المساهمون + + @dependabot[bot], @greysonlalonde, @iris-clawd, @lorenzejay, @lucasgomide, @thiagomoretto + + + + + ## v1.13.0rc1 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.13.0rc1) + + ## ما الذي تغير + + ### الوثائق + - تحديث سجل التغييرات والإصدار لـ v1.13.0a2 + + ## المساهمون + + @greysonlalonde + + + + + ## v1.13.0a2 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.13.0a2) + + ## ما الذي تغير + + ### الميزات + - تحديث تلقائي لمستودع اختبار النشر أثناء الإصدار + - تحسين مرونة إصدار المؤسسات وتجربة المستخدم + + ### الوثائق + - تحديث سجل التغييرات والإصدار للإصدار v1.13.0a1 + + ## المساهمون + + @greysonlalonde + + + + + ## v1.13.0a1 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.13.0a1) + + ## ما الذي تغير + + ### إصلاحات الأخطاء + - إصلاح الروابط المعطلة في سير العمل الوثائقي عن طريق تثبيت Node على LTS 22 + - مسح ذاكرة التخزين المؤقت لـ uv للحزم المنشورة حديثًا في الإصدار المؤسسي + + ### الوثائق + - إضافة مصفوفة شاملة لأذونات RBAC ودليل النشر + - تحديث سجل التغييرات والإصدار للإصدار v1.12.2 + + ## المساهمون + + @greysonlalonde, @iris-clawd, @joaomdmoura + + + + + ## v1.12.2 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.12.2) + + ## ما الذي تغير + + ### الميزات + - إضافة مرحلة إصدار المؤسسات إلى إصدار أدوات المطورين + + ### إصلاحات الأخطاء + - الحفاظ على قيمة إرجاع الطريقة كإخراج تدفق لـ @human_feedback مع emit + + ### الوثائق + - تحديث سجل التغييرات والإصدار لـ v1.12.1 + - مراجعة سياسة الأمان وتعليمات الإبلاغ + + ## المساهمون + + @alex-clawd, @greysonlalonde, @joaomdmoura, @theCyberTech + + + + + ## v1.12.1 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.12.1) + + ## ما الذي تغير + + ### الميزات + - إضافة request_id إلى HumanFeedbackRequestedEvent + - إضافة Qdrant Edge كخلفية تخزين لنظام الذاكرة + - إضافة أمر docs-check لتحليل التغييرات وتوليد الوثائق مع الترجمات + - إضافة دعم اللغة العربية إلى سجل التغييرات وأدوات الإصدار + - إضافة ترجمة باللغة العربية الفصحى لجميع الوثائق + - إضافة أمر تسجيل الخروج في واجهة سطر الأوامر + - إضافة مهارات الوكيل + - تنفيذ root_scope تلقائيًا لعزل الذاكرة الهيكلية + - تنفيذ مزودين متوافقين مع OpenAI (OpenRouter، DeepSeek، Ollama، vLLM، Cerebras، Dashscope) + + ### إصلاحات الأخطاء + - إصلاح بيانات اعتماد غير صحيحة لدفع دفعات التتبع (404) + - حل العديد من الأخطاء في نظام تدفق HITL + - إصلاح حفظ ذاكرة الوكيل + - حل جميع أخطاء mypy الصارمة عبر حزمة crewai + - إصلاح استخدام __router_paths__ لطرق المستمع + الموجه في FlowMeta + - إصلاح خطأ القيمة عند عدم دعم الملفات + - تصحيح صياغة الحجر الصحي لـ litellm في الوثائق + - إصلاح جميع أخطاء mypy في crewai-files وإضافة جميع الحزم إلى فحوصات النوع في CI + - تثبيت الحد الأعلى لـ litellm على آخر إصدار تم اختباره (1.82.6) + + ### الوثائق + - تحديث سجل التغييرات والإصدار لـ v1.12.0 + - إضافة CONTRIBUTING.md + - إضافة دليل لاستخدام CrewAI بدون LiteLLM + + ## المساهمون + + @akaKuruma، @alex-clawd، @greysonlalonde، @iris-clawd، @joaomdmoura، @lorenzejay، @lucasgomide، @nicoferdi96 + + + + + ## v1.12.0 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.12.0) + + ## ما الذي تغير + + ### الميزات + - إضافة واجهة تخزين Qdrant Edge لنظام الذاكرة + - إضافة أمر docs-check لتحليل التغييرات وتوليد الوثائق مع الترجمات + - إضافة دعم اللغة العربية لسجل التغييرات وأدوات الإصدار + - إضافة ترجمة اللغة العربية الفصحى لجميع الوثائق + - إضافة أمر تسجيل الخروج في واجهة سطر الأوامر + - تنفيذ مهارات الوكيل + - تنفيذ نطاق الجذر التلقائي لعزل الذاكرة الهرمية + - تنفيذ موفري خدمات متوافقين مع OpenAI (OpenRouter، DeepSeek، Ollama، vLLM، Cerebras، Dashscope) + + ### إصلاح الأخطاء + - إصلاح بيانات الاعتماد السيئة لدفع دفعات التتبع (404) + - حل العديد من الأخطاء في نظام تدفق HITL + - حل أخطاء mypy في crewai-files وإضافة جميع الحزم إلى فحوصات نوع CI + - حل جميع أخطاء mypy الصارمة عبر حزمة crewai-tools + - حل جميع أخطاء mypy عبر حزمة crewai + - إصلاح حفظ الذاكرة في الوكيل + - إصلاح استخدام __router_paths__ لطرق المستمع + الموجه في FlowMeta + - رفع خطأ القيمة عند عدم دعم الملفات + - تصحيح صياغة الحجر الصحي لـ litellm في الوثائق + - استخدام فحص None بدلاً من isinstance للذاكرة في تعلم التغذية الراجعة البشرية + - تثبيت الحد الأعلى لـ litellm على آخر إصدار تم اختباره (1.82.6) + + ### الوثائق + - تحديث سجل التغييرات والإصدار لـ v1.12.0 + - إضافة CONTRIBUTING.md + - إضافة دليل لاستخدام CrewAI بدون LiteLLM + + ### إعادة الهيكلة + - إعادة هيكلة لتجنب تكرار تنفيذ المهام المتزامنة / غير المتزامنة وبدء التشغيل في الوكيل + - تبسيط الأنابيب الداخلية من litellm (عد الرموز، ردود النداء، اكتشاف الميزات، الأخطاء) + + ## المساهمون + + @akaKuruma، @alex-clawd، @greysonlalonde، @iris-clawd، @joaomdmoura، @lorenzejay، @nicoferdi96 + + + + + ## v1.12.0a3 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.12.0a3) + + ## ما الذي تغير + + ### إصلاحات الأخطاء + - إصلاح بيانات الاعتماد الخاطئة لدفع دفعات التتبع (404) + - حل العديد من الأخطاء في نظام تدفق HITL + + ### الوثائق + - تحديث سجل التغييرات والإصدار لـ v1.12.0a2 + + ## المساهمون + + @akaKuruma, @greysonlalonde + + + + + ## v1.12.0a2 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.12.0a2) + + ## ما الذي تغير + + ### الميزات + - إضافة واجهة تخزين Qdrant Edge لنظام الذاكرة + + ### الوثائق + - تحديث سجل التغييرات والإصدار لـ v1.12.0a1 + + ## المساهمون + + @greysonlalonde + + + + + ## v1.12.0a1 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.12.0a1) + + ## ما الذي تغير + + ### الميزات + - إضافة أمر docs-check لتحليل التغييرات وتوليد الوثائق مع الترجمات + - إضافة دعم اللغة العربية لسجل التغييرات وأدوات الإصدار + - إضافة ترجمة اللغة العربية الفصحى لجميع الوثائق + - إضافة مزودي خدمات متوافقين مع OpenAI (OpenRouter، DeepSeek، Ollama، vLLM، Cerebras، Dashscope) + - إضافة مهارات الوكيل + - إضافة أمر تسجيل الخروج في واجهة سطر الأوامر + - تنفيذ نطاق الجذر التلقائي لعزل الذاكرة الهيكلية + + ### إصلاح الأخطاء + - إصلاح حفظ ذاكرة الوكيل + - حل أخطاء mypy في crewai-files وإضافة جميع الحزم إلى فحوصات نوع CI + - حل جميع أخطاء mypy الصارمة عبر حزمة crewai-tools + - حل جميع أخطاء mypy عبر حزمة crewai + - إصلاح استخدام __router_paths__ لطرق المستمع + الموجه في FlowMeta + - تثبيت الحد الأعلى لـ litellm على آخر إصدار تم اختباره (1.82.6) + - رفع خطأ القيمة عند عدم دعم الملفات + - تصحيح صياغة الحجر الصحي لـ litellm في الوثائق + + ### الوثائق + - إضافة CONTRIBUTING.md + - إضافة دليل لاستخدام CrewAI بدون LiteLLM + - تحديث سجل التغييرات والإصدار لـ v1.11.1 + + ### إعادة الهيكلة + - إعادة هيكلة لإزالة التكرار في تنفيذ المهام المتزامنة وغير المتزامنة وبدء التشغيل في الوكيل + - فصل الأنابيب الداخلية عن litellm (عد الرموز، ردود الفعل، اكتشاف الميزات، الأخطاء) + + ## المساهمون + + @alex-clawd، @greysonlalonde، @iris-clawd، @lorenzejay، @nicoferdi96 + + + + + ## v1.11.1 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.11.1) + + ## ما تغيّر + + ### الميزات + - إضافة مُسلسِل flow_structure() لفحص فئة Flow. + + ### إصلاحات الأخطاء + - إصلاح ثغرات أمنية بتحديث pypdf و tinytag و langchain-core. + - الحفاظ على تهيئة LLM الكاملة عبر استئناف HITL لمزودي غير OpenAI. + - منع اجتياز المسار في FileWriterTool. + - إصلاح انهيار lock_store عندما لا تكون حزمة redis مثبتة. + - تمرير cache_function من BaseTool إلى CrewStructuredTool. + + ### التوثيق + - إضافة دليل نشر الأدوات المخصصة مع الترجمات. + - تحديث سجل التغييرات والإصدار لـ v1.11.0. + - إضافة توثيق مستمعي الأحداث المفقود. + + ### إعادة الهيكلة + - استبدال urllib بـ requests في محمّل PDF. + - استبدال حقول callback والنموذج من نوع Any بأنواع قابلة للتسلسل. + + ## المساهمون + + @alex-clawd, @danielfsbarreto, @dependabot[bot], @greysonlalonde, @lorenzejay, @lucasgomide, @mattatcha, @theCyberTech, @vinibrsl + + + + + ## v1.11.0 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.11.0) + + ## ما تغيّر + + ### التوثيق + - تحديث سجل التغييرات والإصدار لـ v1.11.0rc2 + + ## المساهمون + + @greysonlalonde + + + + + ## v1.11.0rc2 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.11.0rc2) + + ## ما تغيّر + + ### إصلاحات الأخطاء + - تحسين معالجة استجابات LLM والتسلسل. + - ترقية الاعتماديات الانتقالية المعرضة للخطر (authlib، PyJWT، snowflake-connector-python). + - استبدال `os.system` بـ `subprocess.run` في تثبيت pip بالوضع غير الآمن. + + ### التوثيق + - تحديث صفحة أداة Exa Search بتسمية ووصف وخيارات تهيئة محسّنة. + - إضافة خوادم MCP المخصصة في دليل الإرشادات. + - تحديث توثيق جامعي OTEL. + - تحديث توثيق MCP. + - تحديث سجل التغييرات والإصدار لـ v1.11.0rc1. + + ## المساهمون + + @10ishq, @greysonlalonde, @joaomdmoura, @lucasgomide, @mattatcha, @theCyberTech, @vinibrsl + + + + + ## v1.11.0rc1 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.11.0rc1) + + ## ما تغيّر + + ### الميزات + - إضافة مصادقة رمز Plus API في a2a + - تنفيذ نمط التخطيط والتنفيذ + + ### إصلاحات الأخطاء + - حل مشكلة هروب صندوق حماية مفسر الكود + + ### التوثيق + - تحديث سجل التغييرات والإصدار لـ v1.10.2rc2 + + ## المساهمون + + @Copilot, @greysonlalonde, @lorenzejay, @theCyberTech + + + + + ## v1.10.2rc2 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.10.2rc2) + + ## ما تغيّر + + ### إصلاحات الأخطاء + - إزالة الأقفال الحصرية من عمليات التخزين للقراءة فقط + + ### التوثيق + - تحديث سجل التغييرات والإصدار لـ v1.10.2rc1 + + ## المساهمون + + @greysonlalonde + + + + + ## v1.10.2rc1 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.10.2rc1) + + ## ما تغيّر + + ### الميزات + - إضافة أمر الإصدار وتشغيل نشر PyPI + + ### إصلاحات الأخطاء + - إصلاح القفل الآمن عبر العمليات والخيوط للإدخال/الإخراج غير المحمي + - نشر contextvars عبر جميع حدود الخيوط والمنفذين + - نشر ContextVars إلى خيوط المهام غير المتزامنة + + ### التوثيق + - تحديث سجل التغييرات والإصدار لـ v1.10.2a1 + + ## المساهمون + + @danglies007, @greysonlalonde + + + + + ## v1.10.2a1 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.10.2a1) + + ## ما تغيّر + + ### الميزات + - إضافة دعم البحث عن الأدوات وتوفير الرموز وحقن الأدوات المناسبة ديناميكيًا أثناء التنفيذ لـ Anthropic. + - تقديم المزيد من أدوات Brave Search. + - إنشاء إجراء للإصدارات الليلية. + + ### إصلاحات الأخطاء + - إصلاح LockException تحت التنفيذ المتزامن متعدد العمليات. + - حل مشكلات تجميع نتائج الأدوات المتوازية في رسالة مستخدم واحدة. + - معالجة حلول أدوات MCP والقضاء على جميع الاتصالات المشتركة القابلة للتغيير. + - تحديث معالجة معاملات LLM في دالة human_feedback. + - إضافة طرق list/dict المفقودة إلى LockedListProxy و LockedDictProxy. + - نشر سياق contextvars إلى خيوط استدعاء الأدوات المتوازية. + - ترقية اعتمادية gitpython إلى >=3.1.41 لحل ثغرة اجتياز مسار CVE. + + ### إعادة الهيكلة + - إعادة هيكلة فئات الذاكرة لتكون قابلة للتسلسل. + + ### التوثيق + - تحديث سجل التغييرات والإصدار لـ v1.10.1. + + ## المساهمون + + @akaKuruma, @github-actions[bot], @giulio-leone, @greysonlalonde, @joaomdmoura, @jonathansampson, @lorenzejay, @lucasgomide, @mattatcha + + + + + ## v1.10.1 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.10.1) + + ## ما تغيّر + + ### الميزات + - ترقية Gemini GenAI + + ### إصلاحات الأخطاء + - ضبط قيمة مستمع المنفذ لتجنب التكرار + - تجميع أجزاء استجابة الدوال المتوازية في كائن Content واحد في Gemini + - إظهار مخرجات التفكير من نماذج التفكير في Gemini + - تحميل أدوات MCP والمنصة عندما تكون أدوات الوكيل None + - دعم بيئات Jupyter مع حلقات أحداث قيد التشغيل في A2A + - استخدام معرّف مجهول للتتبعات المؤقتة + - تمرير ترويسة plus بشكل مشروط + - تخطي تسجيل معالج الإشارة في الخيوط غير الرئيسية لقياس الأداء عن بعد + - حقن أخطاء الأدوات كملاحظات وحل تعارضات الأسماء + - ترقية pypdf من 4.x إلى 6.7.4 لحل تنبيهات Dependabot + - حل تنبيهات أمان Dependabot الحرجة والعالية + + ### التوثيق + - تحديث توثيق بث webhook + - ضبط لغة التوثيق من AOP إلى AMP + + ### المساهمون + @Vidit-Ostwal, @greysonlalonde, @heitorado, @joaomdmoura, @lorenzejay, @lucasgomide, @mplachta + + diff --git a/docs/ar/concepts/agent-capabilities.mdx b/docs/ar/concepts/agent-capabilities.mdx new file mode 100644 index 000000000..f2a1e142c --- /dev/null +++ b/docs/ar/concepts/agent-capabilities.mdx @@ -0,0 +1,147 @@ +--- +title: "قدرات الوكيل" +description: "فهم الطرق الخمس لتوسيع وكلاء CrewAI: الأدوات، MCP، التطبيقات، المهارات، والمعرفة." +icon: puzzle-piece +mode: "wide" +--- + +## نظرة عامة + +يمكن توسيع وكلاء CrewAI بـ **خمسة أنواع مميزة من القدرات**، كل منها يخدم غرضًا مختلفًا. فهم متى تستخدم كل نوع — وكيف يعملون معًا — هو المفتاح لبناء وكلاء فعّالين. + + + + **دوال قابلة للاستدعاء** — تمنح الوكلاء القدرة على اتخاذ إجراءات. البحث على الويب، عمليات الملفات، استدعاءات API، تنفيذ الكود. + + + **خوادم أدوات عن بُعد** — تربط الوكلاء بخوادم أدوات خارجية عبر Model Context Protocol. نفس تأثير الأدوات، لكن مستضافة خارجيًا. + + + **تكاملات المنصة** — تربط الوكلاء بتطبيقات SaaS (Gmail، Slack، Jira، Salesforce) عبر منصة CrewAI. تعمل محليًا مع رمز تكامل المنصة. + + + **خبرة المجال** — تحقن التعليمات والإرشادات والمواد المرجعية في إرشادات الوكلاء. المهارات تخبر الوكلاء *كيف يفكرون*. + + + **حقائق مُسترجعة** — توفر للوكلاء بيانات من المستندات والملفات وعناوين URL عبر البحث الدلالي (RAG). المعرفة تعطي الوكلاء *ما يحتاجون معرفته*. + + + +--- + +## التمييز الأساسي + +أهم شيء يجب فهمه: **هذه القدرات تنقسم إلى فئتين**. + +### قدرات الإجراء (الأدوات، MCP، التطبيقات) + +تمنح الوكلاء القدرة على **فعل أشياء** — استدعاء APIs، قراءة الملفات، البحث على الويب، إرسال رسائل البريد الإلكتروني. عند التنفيذ، تتحول الأنواع الثلاثة إلى نفس التنسيق الداخلي (مثيلات `BaseTool`) وتظهر في قائمة أدوات موحدة يمكن للوكيل استدعاؤها. + +```python +from crewai import Agent +from crewai_tools import SerperDevTool, FileReadTool + +agent = Agent( + role="Researcher", + goal="Find and compile market data", + backstory="Expert market analyst", + tools=[SerperDevTool(), FileReadTool()], # أدوات محلية + mcps=["https://mcp.example.com/sse"], # أدوات خادم MCP عن بُعد + apps=["gmail", "google_sheets"], # تكاملات المنصة +) +``` + +### قدرات السياق (المهارات، المعرفة) + +تُعدّل **إرشادات** الوكيل — بحقن الخبرة أو التعليمات أو البيانات المُسترجعة قبل أن يبدأ الوكيل في التفكير. لا تمنح الوكلاء إجراءات جديدة؛ بل تُشكّل كيف يفكر الوكلاء وما هي المعلومات التي يمكنهم الوصول إليها. + +```python +from crewai import Agent + +agent = Agent( + role="Security Auditor", + goal="Audit cloud infrastructure for vulnerabilities", + backstory="Expert in cloud security with 10 years of experience", + skills=["./skills/security-audit"], # تعليمات المجال + knowledge_sources=[pdf_source, url_source], # حقائق مُسترجعة +) +``` + +--- + +## متى تستخدم ماذا + +| تحتاج إلى... | استخدم | مثال | +| :------------------------------------------------------- | :---------------- | :--------------------------------------- | +| الوكيل يبحث على الويب | **الأدوات** | `tools=[SerperDevTool()]` | +| الوكيل يستدعي API عن بُعد عبر MCP | **MCP** | `mcps=["https://api.example.com/sse"]` | +| الوكيل يرسل بريد إلكتروني عبر Gmail | **التطبيقات** | `apps=["gmail"]` | +| الوكيل يتبع إجراءات محددة | **المهارات** | `skills=["./skills/code-review"]` | +| الوكيل يرجع لمستندات الشركة | **المعرفة** | `knowledge_sources=[pdf_source]` | +| الوكيل يبحث على الويب ويتبع إرشادات المراجعة | **الأدوات + المهارات** | استخدم كليهما معًا | + +--- + +## دمج القدرات + +في الممارسة العملية، غالبًا ما يستخدم الوكلاء **أنواعًا متعددة من القدرات معًا**. إليك مثال واقعي: + +```python +from crewai import Agent +from crewai_tools import SerperDevTool, FileReadTool, CodeInterpreterTool + +# وكيل بحث مجهز بالكامل +researcher = Agent( + role="Senior Research Analyst", + goal="Produce comprehensive market analysis reports", + backstory="Expert analyst with deep industry knowledge", + + # الإجراء: ما يمكن للوكيل فعله + tools=[ + SerperDevTool(), # البحث على الويب + FileReadTool(), # قراءة الملفات المحلية + CodeInterpreterTool(), # تشغيل كود Python للتحليل + ], + mcps=["https://data-api.example.com/sse"], # الوصول لـ API بيانات عن بُعد + apps=["google_sheets"], # الكتابة في Google Sheets + + # السياق: ما يعرفه الوكيل + skills=["./skills/research-methodology"], # كيفية إجراء البحث + knowledge_sources=[company_docs], # بيانات خاصة بالشركة +) +``` + +--- + +## جدول المقارنة + +| الميزة | الأدوات | MCP | التطبيقات | المهارات | المعرفة | +| :--- | :---: | :---: | :---: | :---: | :---: | +| **يمنح الوكيل إجراءات** | ✅ | ✅ | ✅ | ❌ | ❌ | +| **يُعدّل الإرشادات** | ❌ | ❌ | ❌ | ✅ | ✅ | +| **يتطلب كود** | نعم | إعداد فقط | إعداد فقط | Markdown فقط | إعداد فقط | +| **يعمل محليًا** | نعم | يعتمد | نعم (مع متغير بيئة) | غير متاح | نعم | +| **يحتاج مفاتيح API** | لكل أداة | لكل خادم | رمز التكامل | لا | المُضمّن فقط | +| **يُعيَّن على Agent** | `tools=[]` | `mcps=[]` | `apps=[]` | `skills=[]` | `knowledge_sources=[]` | +| **يُعيَّن على Crew** | ❌ | ❌ | ❌ | `skills=[]` | `knowledge_sources=[]` | + +--- + +## تعمّق أكثر + +هل أنت مستعد لمعرفة المزيد عن كل نوع من أنواع القدرات؟ + + + + إنشاء أدوات مخصصة، استخدام كتالوج OSS مع أكثر من 75 خيارًا، تكوين التخزين المؤقت والتنفيذ غير المتزامن. + + + الاتصال بخوادم MCP عبر stdio أو SSE أو HTTP. تصفية الأدوات، تكوين المصادقة. + + + بناء حزم المهارات مع SKILL.md، حقن خبرة المجال، استخدام الكشف التدريجي. + + + إضافة المعرفة من ملفات PDF وCSV وعناوين URL والمزيد. تكوين المُضمّنات والاسترجاع. + + diff --git a/docs/ar/concepts/agents.mdx b/docs/ar/concepts/agents.mdx new file mode 100644 index 000000000..7ae5c668c --- /dev/null +++ b/docs/ar/concepts/agents.mdx @@ -0,0 +1,357 @@ +--- +title: الوكلاء +description: دليل تفصيلي حول إنشاء وإدارة الوكلاء ضمن إطار عمل CrewAI. +icon: robot +mode: "wide" +--- + +## نظرة عامة على الوكيل + +في إطار عمل CrewAI، الـ `Agent` هو وحدة مستقلة يمكنها: + +- أداء مهام محددة +- اتخاذ قرارات بناءً على دوره وهدفه +- استخدام الأدوات لتحقيق الأهداف +- التواصل والتعاون مع وكلاء آخرين +- الاحتفاظ بذاكرة التفاعلات +- تفويض المهام عند السماح بذلك + + + فكّر في الوكيل كعضو فريق متخصص بمهارات وخبرات ومسؤوليات محددة. + على سبيل المثال، قد يتفوق وكيل `Researcher` في جمع وتحليل المعلومات، + بينما قد يكون وكيل `Writer` أفضل في إنشاء المحتوى. + + + +يتضمن CrewAI AMP منشئ وكلاء مرئي يبسّط إنشاء وتهيئة الوكلاء بدون كتابة كود. صمم وكلاءك بصريًا واختبرهم في الوقت الفعلي. + +![Visual Agent Builder Screenshot](/images/enterprise/crew-studio-interface.png) + +يُمكّن منشئ الوكلاء المرئي من: + +- تهيئة وكلاء بديهية بواجهات نماذج +- اختبار والتحقق في الوقت الفعلي +- مكتبة قوالب مع أنواع وكلاء مهيأة مسبقًا +- تخصيص سهل لخصائص وسلوكيات الوكيل + + +## خصائص الوكيل + +| الخاصية | المعامل | النوع | الوصف | +| :-------------------------------------- | :----------------------- | :------------------------------------ | :------------------------------------------------------------------------------------------------------- | +| **الدور** | `role` | `str` | يحدد وظيفة الوكيل وخبرته ضمن الطاقم. | +| **الهدف** | `goal` | `str` | الهدف الفردي الذي يوجه عملية اتخاذ القرار لدى الوكيل. | +| **الخلفية** | `backstory` | `str` | يوفر سياقًا وشخصية للوكيل، مما يثري التفاعلات. | +| **LLM** _(اختياري)_ | `llm` | `Union[str, LLM, Any]` | نموذج اللغة الذي يشغّل الوكيل. افتراضيًا النموذج المحدد في `OPENAI_MODEL_NAME` أو "gpt-4". | +| **الأدوات** _(اختياري)_ | `tools` | `List[BaseTool]` | القدرات أو الوظائف المتاحة للوكيل. افتراضيًا قائمة فارغة. | +| **LLM استدعاء الدوال** _(اختياري)_ | `function_calling_llm` | `Optional[Any]` | نموذج لغة لاستدعاء الأدوات، يتجاوز LLM الطاقم إذا حُدد. | +| **الحد الأقصى للتكرارات** _(اختياري)_ | `max_iter` | `int` | الحد الأقصى للتكرارات قبل أن يقدم الوكيل أفضل إجابته. الافتراضي 20. | +| **الحد الأقصى لـ RPM** _(اختياري)_ | `max_rpm` | `Optional[int]` | الحد الأقصى للطلبات في الدقيقة لتجنب حدود المعدل. | +| **الحد الأقصى لوقت التنفيذ** _(اختياري)_ | `max_execution_time` | `Optional[int]` | الحد الأقصى للوقت (بالثواني) لتنفيذ المهمة. | +| **الوضع المفصل** _(اختياري)_ | `verbose` | `bool` | تفعيل سجلات التنفيذ المفصلة للتصحيح. الافتراضي False. | +| **السماح بالتفويض** _(اختياري)_ | `allow_delegation` | `bool` | السماح للوكيل بتفويض المهام لوكلاء آخرين. الافتراضي False. | +| **دالة الخطوة** _(اختياري)_ | `step_callback` | `Optional[Any]` | دالة تُستدعى بعد كل خطوة للوكيل، تتجاوز دالة الطاقم. | +| **التخزين المؤقت** _(اختياري)_ | `cache` | `bool` | تفعيل التخزين المؤقت لاستخدام الأدوات. الافتراضي True. | +| **قالب النظام** _(اختياري)_ | `system_template` | `Optional[str]` | قالب أمر نظام مخصص للوكيل. | +| **قالب الأمر** _(اختياري)_ | `prompt_template` | `Optional[str]` | قالب أمر مخصص للوكيل. | +| **قالب الاستجابة** _(اختياري)_ | `response_template` | `Optional[str]` | قالب استجابة مخصص للوكيل. | +| **السماح بتنفيذ الكود** _(اختياري)_ | `allow_code_execution` | `Optional[bool]` | تفعيل تنفيذ الكود للوكيل. الافتراضي False. | +| **الحد الأقصى لإعادة المحاولة** _(اختياري)_ | `max_retry_limit` | `int` | الحد الأقصى لإعادات المحاولة عند حدوث خطأ. الافتراضي 2. | +| **احترام نافذة السياق** _(اختياري)_ | `respect_context_window` | `bool` | إبقاء الرسائل تحت حجم نافذة السياق عبر التلخيص. الافتراضي True. | +| **وضع تنفيذ الكود** _(اختياري)_ | `code_execution_mode` | `Literal["safe", "unsafe"]` | وضع تنفيذ الكود: 'safe' (باستخدام Docker) أو 'unsafe' (مباشر). الافتراضي 'safe'. | +| **متعدد الوسائط** _(اختياري)_ | `multimodal` | `bool` | ما إذا كان الوكيل يدعم القدرات متعددة الوسائط. الافتراضي False. | +| **حقن التاريخ** _(اختياري)_ | `inject_date` | `bool` | ما إذا كان يتم حقن التاريخ الحالي تلقائيًا في المهام. الافتراضي False. | +| **تنسيق التاريخ** _(اختياري)_ | `date_format` | `str` | سلسلة تنسيق التاريخ عند تفعيل inject_date. الافتراضي "%Y-%m-%d" (تنسيق ISO). | +| **الاستدلال** _(اختياري)_ | `reasoning` | `bool` | ما إذا كان يجب على الوكيل التأمل وإنشاء خطة قبل تنفيذ المهمة. الافتراضي False. | +| **الحد الأقصى لمحاولات الاستدلال** _(اختياري)_ | `max_reasoning_attempts` | `Optional[int]` | الحد الأقصى لمحاولات الاستدلال قبل تنفيذ المهمة. إذا None، سيحاول حتى الاستعداد. | +| **المُضمّن** _(اختياري)_ | `embedder` | `Optional[Dict[str, Any]]` | تهيئة المُضمّن المستخدم من قبل الوكيل. | +| **مصادر المعرفة** _(اختياري)_ | `knowledge_sources` | `Optional[List[BaseKnowledgeSource]]` | مصادر المعرفة المتاحة للوكيل. | +| **استخدام أمر النظام** _(اختياري)_ | `use_system_prompt` | `Optional[bool]` | ما إذا كان يُستخدم أمر النظام (لدعم نموذج o1). الافتراضي True. | + +## إنشاء الوكلاء + +هناك طريقتان لإنشاء الوكلاء في CrewAI: باستخدام **تهيئة YAML (موصى بها)** أو تعريفهم **مباشرة في الكود**. + +### تهيئة YAML (موصى بها) + +توفر تهيئة YAML طريقة أنظف وأكثر قابلية للصيانة لتعريف الوكلاء. نوصي بشدة باستخدام هذا النهج في مشاريع CrewAI. + +بعد إنشاء مشروع CrewAI كما هو موضح في قسم [التثبيت](/ar/installation)، انتقل إلى ملف `src/latest_ai_development/config/agents.yaml` وعدّل القالب ليتوافق مع متطلباتك. + + +ستُستبدل المتغيرات في ملفات YAML (مثل `{topic}`) بقيم من مدخلاتك عند تشغيل الطاقم: +```python Code +crew.kickoff(inputs={'topic': 'AI Agents'}) +``` + + +إليك مثالًا على كيفية تهيئة الوكلاء باستخدام YAML: + +```yaml agents.yaml +# src/latest_ai_development/config/agents.yaml +researcher: + role: > + {topic} Senior Data Researcher + goal: > + Uncover cutting-edge developments in {topic} + backstory: > + You're a seasoned researcher with a knack for uncovering the latest + developments in {topic}. Known for your ability to find the most relevant + information and present it in a clear and concise manner. + +reporting_analyst: + role: > + {topic} Reporting Analyst + goal: > + Create detailed reports based on {topic} data analysis and research findings + backstory: > + You're a meticulous analyst with a keen eye for detail. You're known for + your ability to turn complex data into clear and concise reports, making + it easy for others to understand and act on the information you provide. +``` + +لاستخدام تهيئة YAML في الكود، أنشئ فئة طاقم ترث من `CrewBase`: + +```python Code +# src/latest_ai_development/crew.py +from crewai import Agent, Crew, Process +from crewai.project import CrewBase, agent, crew +from crewai_tools import SerperDevTool + +@CrewBase +class LatestAiDevelopmentCrew(): + """LatestAiDevelopment crew""" + + agents_config = "config/agents.yaml" + + @agent + def researcher(self) -> Agent: + return Agent( + config=self.agents_config['researcher'], # type: ignore[index] + verbose=True, + tools=[SerperDevTool()] + ) + + @agent + def reporting_analyst(self) -> Agent: + return Agent( + config=self.agents_config['reporting_analyst'], # type: ignore[index] + verbose=True + ) +``` + + + يجب أن تتطابق الأسماء المستخدمة في ملفات YAML (`agents.yaml`) مع أسماء + الطرق في كود Python. + + +### تعريف مباشر في الكود + +يمكنك إنشاء الوكلاء مباشرة في الكود بإنشاء فئة `Agent`. إليك مثالًا شاملًا يوضح جميع المعاملات المتاحة: + +```python Code +from crewai import Agent +from crewai_tools import SerperDevTool + +# إنشاء وكيل بجميع المعاملات المتاحة +agent = Agent( + role="Senior Data Scientist", + goal="Analyze and interpret complex datasets to provide actionable insights", + backstory="With over 10 years of experience in data science and machine learning, " + "you excel at finding patterns in complex datasets.", + llm="gpt-4", + function_calling_llm=None, + verbose=False, + allow_delegation=False, + max_iter=20, + max_rpm=None, + max_execution_time=None, + max_retry_limit=2, + allow_code_execution=False, + code_execution_mode="safe", + respect_context_window=True, + use_system_prompt=True, + multimodal=False, + inject_date=False, + date_format="%Y-%m-%d", + reasoning=False, + max_reasoning_attempts=None, + tools=[SerperDevTool()], + knowledge_sources=None, + embedder=None, + system_template=None, + prompt_template=None, + response_template=None, + step_callback=None, +) +``` + +دعنا نستعرض بعض تركيبات المعاملات الرئيسية لحالات الاستخدام الشائعة: + +#### وكيل بحث أساسي + +```python Code +research_agent = Agent( + role="Research Analyst", + goal="Find and summarize information about specific topics", + backstory="You are an experienced researcher with attention to detail", + tools=[SerperDevTool()], + verbose=True +) +``` + +#### وكيل تطوير الكود + +```python Code +dev_agent = Agent( + role="Senior Python Developer", + goal="Write and debug Python code", + backstory="Expert Python developer with 10 years of experience", + allow_code_execution=True, + code_execution_mode="safe", + max_execution_time=300, + max_retry_limit=3 +) +``` + +#### وكيل تحليل طويل المدى + +```python Code +analysis_agent = Agent( + role="Data Analyst", + goal="Perform deep analysis of large datasets", + backstory="Specialized in big data analysis and pattern recognition", + memory=True, + respect_context_window=True, + max_rpm=10, + function_calling_llm="gpt-4o-mini" +) +``` + +### تفاصيل المعاملات + +#### المعاملات الحرجة + +- `role` و `goal` و `backstory` مطلوبة وتشكّل سلوك الوكيل +- `llm` يحدد نموذج اللغة المستخدم (افتراضي: GPT-4 من OpenAI) + +#### الذاكرة والسياق + +- `memory`: تفعيل للحفاظ على سجل المحادثة +- `respect_context_window`: يمنع مشاكل حد الرموز +- `knowledge_sources`: إضافة قواعد معرفة خاصة بالمجال + +#### التحكم في التنفيذ + +- `max_iter`: الحد الأقصى للمحاولات قبل تقديم أفضل إجابة +- `max_execution_time`: المهلة بالثواني +- `max_rpm`: تحديد معدل استدعاءات API +- `max_retry_limit`: إعادات المحاولة عند الخطأ + +#### تنفيذ الكود + + + `allow_code_execution` و`code_execution_mode` مهجوران. تمت إزالة `CodeInterpreterTool` من `crewai-tools`. استخدم خدمة بيئة معزولة مخصصة مثل [E2B](https://e2b.dev) أو [Modal](https://modal.com) لتنفيذ الكود بأمان. + + +- `allow_code_execution` _(مهجور)_: كان يُمكّن تنفيذ الكود المدمج عبر `CodeInterpreterTool`. +- `code_execution_mode` _(مهجور)_: كان يتحكم في وضع التنفيذ (`"safe"` لـ Docker، `"unsafe"` للتنفيذ المباشر). + +#### الميزات المتقدمة + +- `multimodal`: تفعيل القدرات متعددة الوسائط لمعالجة النص والمحتوى المرئي +- `reasoning`: تمكين الوكيل من التأمل وإنشاء خطط قبل تنفيذ المهام +- `inject_date`: حقن التاريخ الحالي تلقائيًا في أوصاف المهام + +#### القوالب + +- `system_template`: يحدد السلوك الأساسي للوكيل +- `prompt_template`: ينظم تنسيق الإدخال +- `response_template`: ينسّق استجابات الوكيل + + + عند استخدام القوالب المخصصة، تأكد من تعريف كل من `system_template` و + `prompt_template`. `response_template` اختياري لكن يُوصى به + لتنسيق مخرجات متسق. + + +## أدوات الوكيل + +يمكن تجهيز الوكلاء بأدوات متنوعة لتعزيز قدراتهم. يدعم CrewAI أدوات من: + +- [مجموعة أدوات CrewAI](https://github.com/joaomdmoura/crewai-tools) +- [أدوات LangChain](https://python.langchain.com/docs/integrations/tools) + +إليك كيفية إضافة أدوات لوكيل: + +```python Code +from crewai import Agent +from crewai_tools import SerperDevTool, WikipediaTools + +# إنشاء الأدوات +search_tool = SerperDevTool() +wiki_tool = WikipediaTools() + +# إضافة أدوات للوكيل +researcher = Agent( + role="AI Technology Researcher", + goal="Research the latest AI developments", + tools=[search_tool, wiki_tool], + verbose=True +) +``` + +## التفاعل المباشر مع الوكيل عبر `kickoff()` + +يمكن استخدام الوكلاء مباشرة بدون المرور بمهمة أو سير عمل طاقم باستخدام طريقة `kickoff()`. يوفر هذا طريقة أبسط للتفاعل مع وكيل عندما لا تحتاج إلى إمكانيات تنسيق الطاقم الكاملة. + +```python Code +from crewai import Agent +from crewai_tools import SerperDevTool + +# إنشاء وكيل +researcher = Agent( + role="AI Technology Researcher", + goal="Research the latest AI developments", + tools=[SerperDevTool()], + verbose=True +) + +# استخدام kickoff() للتفاعل مباشرة مع الوكيل +result = researcher.kickoff("What are the latest developments in language models?") + +# الوصول إلى الاستجابة الخام +print(result.raw) +``` + +## اعتبارات مهمة وأفضل الممارسات + +### الأمان وتنفيذ الكود + + + `allow_code_execution` و`code_execution_mode` مهجوران وتمت إزالة `CodeInterpreterTool`. استخدم خدمة بيئة معزولة مخصصة مثل [E2B](https://e2b.dev) أو [Modal](https://modal.com) لتنفيذ الكود بأمان. + + +### تحسين الأداء + +- استخدم `respect_context_window: true` لمنع مشاكل حد الرموز +- عيّن `max_rpm` مناسبًا لتجنب تحديد المعدل +- فعّل `cache: true` لتحسين الأداء للمهام المتكررة +- اضبط `max_iter` و `max_retry_limit` بناءً على تعقيد المهمة + +### إدارة الذاكرة والسياق + +- استفد من `knowledge_sources` للمعلومات الخاصة بالمجال +- هيّئ `embedder` عند استخدام نماذج تضمين مخصصة +- استخدم القوالب المخصصة للتحكم الدقيق في سلوك الوكيل + +### التعاون بين الوكلاء + +- فعّل `allow_delegation: true` عندما يحتاج الوكلاء للعمل معًا +- استخدم `step_callback` لمراقبة وتسجيل تفاعلات الوكلاء +- فكّر في استخدام نماذج LLM مختلفة لأغراض مختلفة + +### توافق النموذج + +- عيّن `use_system_prompt: false` للنماذج القديمة التي لا تدعم رسائل النظام +- تأكد من أن `llm` المختار يدعم الميزات التي تحتاجها diff --git a/docs/ar/concepts/checkpointing.mdx b/docs/ar/concepts/checkpointing.mdx new file mode 100644 index 000000000..578f04be9 --- /dev/null +++ b/docs/ar/concepts/checkpointing.mdx @@ -0,0 +1,229 @@ +--- +title: Checkpointing +description: حفظ حالة التنفيذ تلقائيا حتى تتمكن الطواقم والتدفقات والوكلاء من الاستئناف بعد الفشل. +icon: floppy-disk +mode: "wide" +--- + + +الـ Checkpointing في اصدار مبكر. قد تتغير واجهات البرمجة في الاصدارات المستقبلية. + + +## نظرة عامة + +يقوم الـ Checkpointing بحفظ حالة التنفيذ تلقائيا اثناء التشغيل. اذا فشل طاقم او تدفق او وكيل اثناء التنفيذ، يمكنك الاستعادة من اخر نقطة حفظ والاستئناف دون اعادة تنفيذ العمل المكتمل. + +## البداية السريعة + +```python +from crewai import Crew, CheckpointConfig + +crew = Crew( + agents=[...], + tasks=[...], + checkpoint=True, # يستخدم الافتراضيات: ./.checkpoints, عند task_completed +) +result = crew.kickoff() +``` + +تتم كتابة ملفات نقاط الحفظ في `./.checkpoints/` بعد اكتمال كل مهمة. + +## التكوين + +استخدم `CheckpointConfig` للتحكم الكامل: + +```python +from crewai import Crew, CheckpointConfig + +crew = Crew( + agents=[...], + tasks=[...], + checkpoint=CheckpointConfig( + location="./my_checkpoints", + on_events=["task_completed", "crew_kickoff_completed"], + max_checkpoints=5, + ), +) +``` + +### حقول CheckpointConfig + +| الحقل | النوع | الافتراضي | الوصف | +|:------|:------|:----------|:------| +| `location` | `str` | `"./.checkpoints"` | مسار ملفات نقاط الحفظ | +| `on_events` | `list[str]` | `["task_completed"]` | انواع الاحداث التي تطلق نقطة حفظ | +| `provider` | `BaseProvider` | `JsonProvider()` | واجهة التخزين | +| `max_checkpoints` | `int \| None` | `None` | الحد الاقصى للملفات؛ يتم حذف الاقدم اولا | + +### الوراثة والانسحاب + +يقبل حقل `checkpoint` في Crew و Flow و Agent قيم `CheckpointConfig` او `True` او `False` او `None`: + +| القيمة | السلوك | +|:-------|:-------| +| `None` (افتراضي) | يرث من الاصل. الوكيل يرث اعدادات الطاقم. | +| `True` | تفعيل بالاعدادات الافتراضية. | +| `False` | انسحاب صريح. يوقف الوراثة من الاصل. | +| `CheckpointConfig(...)` | اعدادات مخصصة. | + +```python +crew = Crew( + agents=[ + Agent(role="Researcher", ...), # يرث checkpoint من الطاقم + Agent(role="Writer", ..., checkpoint=False), # منسحب، بدون نقاط حفظ + ], + tasks=[...], + checkpoint=True, +) +``` + +## الاستئناف من نقطة حفظ + +```python +# استعادة واستئناف +crew = Crew.from_checkpoint("./my_checkpoints/20260407T120000_abc123.json") +result = crew.kickoff() # يستأنف من اخر مهمة مكتملة +``` + +يتخطى الطاقم المستعاد المهام المكتملة ويستأنف من اول مهمة غير مكتملة. + +## يعمل على Crew و Flow و Agent + +### Crew + +```python +crew = Crew( + agents=[researcher, writer], + tasks=[research_task, write_task, review_task], + checkpoint=CheckpointConfig(location="./crew_cp"), +) +``` + +المشغل الافتراضي: `task_completed` (نقطة حفظ واحدة لكل مهمة مكتملة). + +### Flow + +```python +from crewai.flow.flow import Flow, start, listen +from crewai import CheckpointConfig + +class MyFlow(Flow): + @start() + def step_one(self): + return "data" + + @listen(step_one) + def step_two(self, data): + return process(data) + +flow = MyFlow( + checkpoint=CheckpointConfig( + location="./flow_cp", + on_events=["method_execution_finished"], + ), +) +result = flow.kickoff() + +# استئناف +flow = MyFlow.from_checkpoint("./flow_cp/20260407T120000_abc123.json") +result = flow.kickoff() +``` + +### Agent + +```python +agent = Agent( + role="Researcher", + goal="Research topics", + backstory="Expert researcher", + checkpoint=CheckpointConfig( + location="./agent_cp", + on_events=["lite_agent_execution_completed"], + ), +) +result = agent.kickoff(messages=[{"role": "user", "content": "Research AI trends"}]) +``` + +## مزودات التخزين + +يتضمن CrewAI مزودي تخزين لنقاط الحفظ. + +### JsonProvider (افتراضي) + +يكتب كل نقطة حفظ كملف JSON منفصل. + +```python +from crewai import Crew, CheckpointConfig +from crewai.state import JsonProvider + +crew = Crew( + agents=[...], + tasks=[...], + checkpoint=CheckpointConfig( + location="./my_checkpoints", + provider=JsonProvider(), + max_checkpoints=5, + ), +) +``` + +### SqliteProvider + +يخزن جميع نقاط الحفظ في ملف قاعدة بيانات SQLite واحد. + +```python +from crewai import Crew, CheckpointConfig +from crewai.state import SqliteProvider + +crew = Crew( + agents=[...], + tasks=[...], + checkpoint=CheckpointConfig( + location="./.checkpoints.db", + provider=SqliteProvider(), + ), +) +``` + + +## انواع الاحداث + +يقبل حقل `on_events` اي مجموعة من سلاسل انواع الاحداث. الخيارات الشائعة: + +| حالة الاستخدام | الاحداث | +|:---------------|:--------| +| بعد كل مهمة (Crew) | `["task_completed"]` | +| بعد كل طريقة في التدفق | `["method_execution_finished"]` | +| بعد تنفيذ الوكيل | `["agent_execution_completed"]`, `["lite_agent_execution_completed"]` | +| عند اكتمال الطاقم فقط | `["crew_kickoff_completed"]` | +| بعد كل استدعاء LLM | `["llm_call_completed"]` | +| على كل شيء | `["*"]` | + + +استخدام `["*"]` او احداث عالية التردد مثل `llm_call_completed` سيكتب العديد من ملفات نقاط الحفظ وقد يؤثر على الاداء. استخدم `max_checkpoints` للحد من استخدام المساحة. + + +## نقاط الحفظ اليدوية + +للتحكم الكامل، سجل معالج الاحداث الخاص بك واستدع `state.checkpoint()` مباشرة: + +```python +from crewai.events.event_bus import crewai_event_bus +from crewai.events.types.llm_events import LLMCallCompletedEvent + +# معالج متزامن +@crewai_event_bus.on(LLMCallCompletedEvent) +def on_llm_done(source, event, state): + path = state.checkpoint("./my_checkpoints") + print(f"تم حفظ نقطة الحفظ: {path}") + +# معالج غير متزامن +@crewai_event_bus.on(LLMCallCompletedEvent) +async def on_llm_done_async(source, event, state): + path = await state.acheckpoint("./my_checkpoints") + print(f"تم حفظ نقطة الحفظ: {path}") +``` + +وسيط `state` هو `RuntimeState` الذي يتم تمريره تلقائيا بواسطة ناقل الاحداث عندما يقبل المعالج 3 معاملات. يمكنك تسجيل معالجات على اي نوع حدث مدرج في وثائق [Event Listeners](/ar/concepts/event-listener). + +الـ Checkpointing يعمل بافضل جهد: اذا فشلت كتابة نقطة حفظ، يتم تسجيل الخطأ ولكن التنفيذ يستمر دون انقطاع. diff --git a/docs/ar/concepts/cli.mdx b/docs/ar/concepts/cli.mdx new file mode 100644 index 000000000..e18a450d0 --- /dev/null +++ b/docs/ar/concepts/cli.mdx @@ -0,0 +1,287 @@ +--- +title: واجهة سطر الأوامر +description: تعرّف على كيفية استخدام واجهة سطر أوامر CrewAI للتفاعل مع CrewAI. +icon: terminal +mode: "wide" +--- + + + منذ الإصدار 0.140.0، بدأ CrewAI AMP عملية نقل مزود تسجيل الدخول. + لذلك، تم تحديث تدفق المصادقة عبر CLI. المستخدمون الذين يسجلون الدخول + باستخدام Google، أو الذين أنشأوا حساباتهم بعد 3 يوليو 2025 لن يتمكنوا + من تسجيل الدخول مع الإصدارات القديمة من مكتبة `crewai`. + + +## نظرة عامة + +توفر واجهة سطر أوامر CrewAI مجموعة من الأوامر للتفاعل مع CrewAI، مما يتيح لك إنشاء وتدريب وتشغيل وإدارة الأطقم والتدفقات. + +## التثبيت + +لاستخدام واجهة سطر أوامر CrewAI، تأكد من تثبيت CrewAI: + +```shell Terminal +pip install crewai +``` + +## الاستخدام الأساسي + +الهيكل الأساسي لأمر CrewAI CLI هو: + +```shell Terminal +crewai [COMMAND] [OPTIONS] [ARGUMENTS] +``` + +## الأوامر المتاحة + +### 1. إنشاء + +إنشاء طاقم أو تدفق جديد. + +```shell Terminal +crewai create [OPTIONS] TYPE NAME +``` + +- `TYPE`: اختر بين "crew" أو "flow" +- `NAME`: اسم الطاقم أو التدفق + +مثال: + +```shell Terminal +crewai create crew my_new_crew +crewai create flow my_new_flow +``` + +### 2. الإصدار + +عرض الإصدار المثبت من CrewAI. + +```shell Terminal +crewai version [OPTIONS] +``` + +- `--tools`: (اختياري) عرض الإصدار المثبت من أدوات CrewAI + +### 3. التدريب + +تدريب الطاقم لعدد محدد من التكرارات. + +```shell Terminal +crewai train [OPTIONS] +``` + +- `-n, --n_iterations INTEGER`: عدد تكرارات التدريب (افتراضي: 5) +- `-f, --filename TEXT`: مسار ملف مخصص للتدريب (افتراضي: "trained_agents_data.pkl") + +### 4. الإعادة + +إعادة تنفيذ الطاقم من مهمة محددة. + +```shell Terminal +crewai replay [OPTIONS] +``` + +- `-t, --task_id TEXT`: إعادة تنفيذ الطاقم من معرّف المهمة هذا، بما في ذلك جميع المهام اللاحقة + +### 5. سجل مخرجات المهام + +استرجاع أحدث مخرجات مهام crew.kickoff(). + +```shell Terminal +crewai log-tasks-outputs +``` + +### 6. إعادة تعيين الذاكرة + +إعادة تعيين ذاكرة الطاقم (طويلة، قصيرة، الكيانات، أحدث مخرجات التشغيل). + +```shell Terminal +crewai reset-memories [OPTIONS] +``` + +- `-l, --long`: إعادة تعيين الذاكرة طويلة المدى +- `-s, --short`: إعادة تعيين الذاكرة قصيرة المدى +- `-e, --entities`: إعادة تعيين ذاكرة الكيانات +- `-k, --kickoff-outputs`: إعادة تعيين أحدث مخرجات التشغيل +- `-kn, --knowledge`: إعادة تعيين تخزين المعرفة +- `-akn, --agent-knowledge`: إعادة تعيين تخزين معرفة الوكيل +- `-a, --all`: إعادة تعيين جميع الذاكرات + +### 7. الاختبار + +اختبار الطاقم وتقييم النتائج. + +```shell Terminal +crewai test [OPTIONS] +``` + +- `-n, --n_iterations INTEGER`: عدد تكرارات الاختبار (افتراضي: 3) +- `-m, --model TEXT`: نموذج LLM لتشغيل الاختبارات (افتراضي: "gpt-4o-mini") + +### 8. التشغيل + +تشغيل الطاقم أو التدفق. + +```shell Terminal +crewai run +``` + + + بدءًا من الإصدار 0.103.0، يمكن استخدام أمر `crewai run` لتشغيل + كل من الأطقم القياسية والتدفقات. للتدفقات، يكتشف تلقائيًا النوع + من pyproject.toml ويشغّل الأمر المناسب. هذه هي الطريقة الموصى بها + لتشغيل كل من الأطقم والتدفقات. + + +### 9. الدردشة + +بدءًا من الإصدار `0.98.0`، عند تشغيل أمر `crewai chat`، تبدأ جلسة تفاعلية مع طاقمك. سيرشدك المساعد الذكي بطلب المدخلات اللازمة لتنفيذ الطاقم. بمجرد توفير جميع المدخلات، سينفذ الطاقم مهامه. + +```shell Terminal +crewai chat +``` + + +مهم: عيّن خاصية `chat_llm` في ملف `crew.py` لتفعيل هذا الأمر. + +```python +@crew +def crew(self) -> Crew: + return Crew( + agents=self.agents, + tasks=self.tasks, + process=Process.sequential, + verbose=True, + chat_llm="gpt-4o", + ) +``` + + +### 10. النشر + +نشر الطاقم أو التدفق إلى [CrewAI AMP](https://app.crewai.com). + +- **المصادقة**: تحتاج لتكون مصادقًا للنشر إلى CrewAI AMP. + + ```shell Terminal + crewai login + ``` + +- **إنشاء نشر**: + ```shell Terminal + crewai deploy create + ``` + +- **نشر الطاقم**: + ```shell Terminal + crewai deploy push + ``` + +- **حالة النشر**: + ```shell Terminal + crewai deploy status + ``` + +- **سجلات النشر**: + ```shell Terminal + crewai deploy logs + ``` + +- **عرض النشرات**: + ```shell Terminal + crewai deploy list + ``` + +- **حذف النشر**: + ```shell Terminal + crewai deploy remove + ``` + +### 11. إدارة المؤسسة + +إدارة مؤسسات CrewAI AMP. + +```shell Terminal +crewai org [COMMAND] [OPTIONS] +``` + +- `list`: عرض جميع المؤسسات +- `current`: عرض المؤسسة النشطة حاليًا +- `switch`: التبديل إلى مؤسسة محددة + +### 12. تسجيل الدخول + +المصادقة مع CrewAI AMP باستخدام تدفق رمز الجهاز الآمن. + +```shell Terminal +crewai login +``` + +### 13. إدارة التهيئة + +إدارة إعدادات تهيئة CLI لـ CrewAI. + +```shell Terminal +crewai config [COMMAND] [OPTIONS] +``` + +- `list`: عرض جميع معاملات التهيئة +- `set`: تعيين معامل تهيئة +- `reset`: إعادة تعيين جميع المعاملات إلى القيم الافتراضية + +### 14. إدارة التتبع + +إدارة تفضيلات جمع التتبع لعمليات الطاقم والتدفق. + +```shell Terminal +crewai traces [COMMAND] +``` + +- `enable`: تفعيل جمع التتبع +- `disable`: تعطيل جمع التتبع +- `status`: عرض حالة جمع التتبع الحالية + +#### كيف يعمل التتبع + +يتم التحكم في جمع التتبع بفحص ثلاثة إعدادات بترتيب الأولوية: + +1. **علامة صريحة في الكود** (الأولوية الأعلى): + ```python + crew = Crew(agents=[...], tasks=[...], tracing=True) # تفعيل دائمًا + crew = Crew(agents=[...], tasks=[...], tracing=False) # تعطيل دائمًا + crew = Crew(agents=[...], tasks=[...]) # فحص الأولويات الأدنى + ``` + +2. **متغير البيئة** (الأولوية الثانية): + ```env + CREWAI_TRACING_ENABLED=true + ``` + +3. **تفضيل المستخدم** (الأولوية الأدنى): + ```shell Terminal + crewai traces enable + ``` + + +**لتفعيل التتبع**، استخدم أيًا من هذه الطرق: +- عيّن `tracing=True` في كود الطاقم/التدفق، أو +- أضف `CREWAI_TRACING_ENABLED=true` إلى ملف `.env`، أو +- شغّل `crewai traces enable` + +**لتعطيل التتبع**، استخدم أيًا من هذه الطرق: +- عيّن `tracing=False` في كود الطاقم/التدفق، أو +- أزل أو عيّن `false` لمتغير `CREWAI_TRACING_ENABLED`، أو +- شغّل `crewai traces disable` + + + + يتعامل CrewAI CLI مع المصادقة لمستودع الأدوات تلقائيًا عند + إضافة حزم إلى مشروعك. فقط أضف `crewai` قبل أي أمر `uv` + لاستخدامه. مثلًا `crewai uv add requests`. + + + + تُخزن إعدادات التهيئة في `~/.config/crewai/settings.json`. بعض + الإعدادات مثل اسم المؤسسة ومعرّفها للقراءة فقط وتُدار من خلال + أوامر المصادقة والمؤسسة. + diff --git a/docs/ar/concepts/collaboration.mdx b/docs/ar/concepts/collaboration.mdx new file mode 100644 index 000000000..a0cae9139 --- /dev/null +++ b/docs/ar/concepts/collaboration.mdx @@ -0,0 +1,363 @@ +--- +title: التعاون +description: كيفية تمكين الوكلاء من العمل معًا وتفويض المهام والتواصل بفعالية داخل فرق CrewAI. +icon: screen-users +mode: "wide" +--- + +## نظرة عامة + +يُمكّن التعاون في CrewAI الوكلاء من العمل معًا كفريق عن طريق تفويض المهام وطرح الأسئلة للاستفادة من خبرات بعضهم البعض. عندما يكون `allow_delegation=True`، يحصل الوكلاء تلقائيًا على أدوات تعاون قوية. + +## البدء السريع: تفعيل التعاون + +```python +from crewai import Agent, Crew, Task + +# تفعيل التعاون للوكلاء +researcher = Agent( + role="Research Specialist", + goal="Conduct thorough research on any topic", + backstory="Expert researcher with access to various sources", + allow_delegation=True, # الإعداد الرئيسي للتعاون + verbose=True +) + +writer = Agent( + role="Content Writer", + goal="Create engaging content based on research", + backstory="Skilled writer who transforms research into compelling content", + allow_delegation=True, # يُمكّن طرح الأسئلة على الوكلاء الآخرين + verbose=True +) + +# يمكن للوكلاء الآن التعاون تلقائيًا +crew = Crew( + agents=[researcher, writer], + tasks=[...], + verbose=True +) +``` + +## كيف يعمل تعاون الوكلاء + +عندما يكون `allow_delegation=True`، يوفر CrewAI تلقائيًا للوكلاء أداتين قويتين: + +### 1. **أداة تفويض العمل** +تسمح للوكلاء بتعيين مهام لزملاء الفريق ذوي الخبرة المحددة. + +```python +# يحصل الوكيل تلقائيًا على هذه الأداة: +# Delegate work to coworker(task: str, context: str, coworker: str) +``` + +### 2. **أداة طرح الأسئلة** +تُمكّن الوكلاء من طرح أسئلة محددة لجمع المعلومات من الزملاء. + +```python +# يحصل الوكيل تلقائيًا على هذه الأداة: +# Ask question to coworker(question: str, context: str, coworker: str) +``` + +## التعاون في الممارسة + +إليك مثالًا كاملًا يوضح تعاون الوكلاء في مهمة إنشاء المحتوى: + +```python +from crewai import Agent, Crew, Task, Process + +# إنشاء وكلاء تعاونيين +researcher = Agent( + role="Research Specialist", + goal="Find accurate, up-to-date information on any topic", + backstory="""You're a meticulous researcher with expertise in finding + reliable sources and fact-checking information across various domains.""", + allow_delegation=True, + verbose=True +) + +writer = Agent( + role="Content Writer", + goal="Create engaging, well-structured content", + backstory="""You're a skilled content writer who excels at transforming + research into compelling, readable content for different audiences.""", + allow_delegation=True, + verbose=True +) + +editor = Agent( + role="Content Editor", + goal="Ensure content quality and consistency", + backstory="""You're an experienced editor with an eye for detail, + ensuring content meets high standards for clarity and accuracy.""", + allow_delegation=True, + verbose=True +) + +# إنشاء مهمة تشجع التعاون +article_task = Task( + description="""Write a comprehensive 1000-word article about 'The Future of AI in Healthcare'. + + The article should include: + - Current AI applications in healthcare + - Emerging trends and technologies + - Potential challenges and ethical considerations + - Expert predictions for the next 5 years + + Collaborate with your teammates to ensure accuracy and quality.""", + expected_output="A well-researched, engaging 1000-word article with proper structure and citations", + agent=writer # الكاتب يقود، لكن يمكنه تفويض البحث إلى الباحث +) + +# إنشاء طاقم تعاوني +crew = Crew( + agents=[researcher, writer, editor], + tasks=[article_task], + process=Process.sequential, + verbose=True +) + +result = crew.kickoff() +``` + +## أنماط التعاون + +### النمط 1: بحث ← كتابة ← تحرير +```python +research_task = Task( + description="Research the latest developments in quantum computing", + expected_output="Comprehensive research summary with key findings and sources", + agent=researcher +) + +writing_task = Task( + description="Write an article based on the research findings", + expected_output="Engaging 800-word article about quantum computing", + agent=writer, + context=[research_task] # يحصل على مخرجات البحث كسياق +) + +editing_task = Task( + description="Edit and polish the article for publication", + expected_output="Publication-ready article with improved clarity and flow", + agent=editor, + context=[writing_task] # يحصل على مسودة المقال كسياق +) +``` + +### النمط 2: مهمة واحدة تعاونية +```python +collaborative_task = Task( + description="""Create a marketing strategy for a new AI product. + + Writer: Focus on messaging and content strategy + Researcher: Provide market analysis and competitor insights + + Work together to create a comprehensive strategy.""", + expected_output="Complete marketing strategy with research backing", + agent=writer # الوكيل القائد، لكن يمكنه التفويض إلى الباحث +) +``` + +## التعاون الهرمي + +للمشاريع المعقدة، استخدم عملية هرمية مع وكيل مدير: + +```python +from crewai import Agent, Crew, Task, Process + +# وكيل المدير ينسق الفريق +manager = Agent( + role="Project Manager", + goal="Coordinate team efforts and ensure project success", + backstory="Experienced project manager skilled at delegation and quality control", + allow_delegation=True, + verbose=True +) + +# وكلاء متخصصون +researcher = Agent( + role="Researcher", + goal="Provide accurate research and analysis", + backstory="Expert researcher with deep analytical skills", + allow_delegation=False, # المتخصصون يركزون على خبرتهم + verbose=True +) + +writer = Agent( + role="Writer", + goal="Create compelling content", + backstory="Skilled writer who creates engaging content", + allow_delegation=False, + verbose=True +) + +# مهمة يقودها المدير +project_task = Task( + description="Create a comprehensive market analysis report with recommendations", + expected_output="Executive summary, detailed analysis, and strategic recommendations", + agent=manager # المدير سيفوّض إلى المتخصصين +) + +# طاقم هرمي +crew = Crew( + agents=[manager, researcher, writer], + tasks=[project_task], + process=Process.hierarchical, # المدير ينسق كل شيء + manager_llm="gpt-4o", # تحديد LLM للمدير + verbose=True +) +``` + +## أفضل ممارسات التعاون + +### 1. **تحديد الأدوار بوضوح** +```python +# جيد: أدوار محددة ومتكاملة +researcher = Agent(role="Market Research Analyst", ...) +writer = Agent(role="Technical Content Writer", ...) + +# تجنب: أدوار متداخلة أو غامضة +agent1 = Agent(role="General Assistant", ...) +agent2 = Agent(role="Helper", ...) +``` + +### 2. **تفعيل التفويض الاستراتيجي** +```python +# فعّل التفويض للمنسقين والعامين +lead_agent = Agent( + role="Content Lead", + allow_delegation=True, # يمكنه التفويض إلى المتخصصين + ... +) + +# عطّل للمتخصصين المركّزين (اختياري) +specialist_agent = Agent( + role="Data Analyst", + allow_delegation=False, # يركز على الخبرة الأساسية + ... +) +``` + +### 3. **مشاركة السياق** +```python +# استخدم معامل context لاعتماديات المهام +writing_task = Task( + description="Write article based on research", + agent=writer, + context=[research_task], # يشارك نتائج البحث + ... +) +``` + +### 4. **أوصاف المهام الواضحة** +```python +# أوصاف محددة وقابلة للتنفيذ +Task( + description="""Research competitors in the AI chatbot space. + Focus on: pricing models, key features, target markets. + Provide data in a structured format.""", + ... +) + +# تجنب: أوصاف غامضة لا توجه التعاون +Task(description="Do some research about chatbots", ...) +``` + +## استكشاف أخطاء التعاون وإصلاحها + +### المشكلة: الوكلاء لا يتعاونون +**الأعراض:** يعمل الوكلاء بمعزل، لا يحدث تفويض +```python +# الحل: تأكد من تفعيل التفويض +agent = Agent( + role="...", + allow_delegation=True, # هذا مطلوب! + ... +) +``` + +### المشكلة: كثرة الذهاب والإياب +**الأعراض:** يطرح الوكلاء أسئلة مفرطة، تقدم بطيء +```python +# الحل: وفّر سياقًا أفضل وأدوارًا محددة +Task( + description="""Write a technical blog post about machine learning. + + Context: Target audience is software developers with basic ML knowledge. + Length: 1200 words + Include: code examples, practical applications, best practices + + If you need specific technical details, delegate research to the researcher.""", + ... +) +``` + +### المشكلة: حلقات التفويض +**الأعراض:** يفوّض الوكلاء ذهابًا وإيابًا بلا نهاية +```python +# الحل: تسلسل هرمي واضح ومسؤوليات +manager = Agent(role="Manager", allow_delegation=True) +specialist1 = Agent(role="Specialist A", allow_delegation=False) # لا إعادة تفويض +specialist2 = Agent(role="Specialist B", allow_delegation=False) +``` + +## ميزات التعاون المتقدمة + +### قواعد التعاون المخصصة +```python +# تعيين إرشادات تعاون محددة في خلفية الوكيل +agent = Agent( + role="Senior Developer", + backstory="""You lead development projects and coordinate with team members. + + Collaboration guidelines: + - Delegate research tasks to the Research Analyst + - Ask the Designer for UI/UX guidance + - Consult the QA Engineer for testing strategies + - Only escalate blocking issues to the Project Manager""", + allow_delegation=True +) +``` + +### مراقبة التعاون +```python +def track_collaboration(output): + """تتبع أنماط التعاون""" + if "Delegate work to coworker" in output.raw: + print("Delegation occurred") + if "Ask question to coworker" in output.raw: + print("Question asked") + +crew = Crew( + agents=[...], + tasks=[...], + step_callback=track_collaboration, # مراقبة التعاون + verbose=True +) +``` + +## الذاكرة والتعلم + +تمكين الوكلاء من تذكر التعاونات السابقة: + +```python +agent = Agent( + role="Content Lead", + memory=True, # يتذكر التفاعلات السابقة + allow_delegation=True, + verbose=True +) +``` + +مع تفعيل الذاكرة، يتعلم الوكلاء من التعاونات السابقة ويحسّنون قرارات التفويض بمرور الوقت. + +## الخطوات التالية + +- **جرّب الأمثلة**: ابدأ بمثال التعاون الأساسي +- **جرّب أدوارًا مختلفة**: اختبر تركيبات أدوار وكلاء مختلفة +- **راقب التفاعلات**: استخدم `verbose=True` لرؤية التعاون في العمل +- **حسّن أوصاف المهام**: المهام الواضحة تؤدي إلى تعاون أفضل +- **وسّع النطاق**: جرّب العمليات الهرمية للمشاريع المعقدة + +يحوّل التعاون وكلاء الذكاء الاصطناعي الفرديين إلى فرق قوية يمكنها معالجة التحديات المعقدة ومتعددة الأوجه معًا. diff --git a/docs/ar/concepts/crews.mdx b/docs/ar/concepts/crews.mdx new file mode 100644 index 000000000..9b622dd0b --- /dev/null +++ b/docs/ar/concepts/crews.mdx @@ -0,0 +1,204 @@ +--- +title: الأطقم +description: فهم واستخدام الأطقم في إطار عمل CrewAI مع خصائص ووظائف شاملة. +icon: people-group +mode: "wide" +--- + +## نظرة عامة + +يمثل الطاقم في CrewAI مجموعة تعاونية من الوكلاء يعملون معًا لتحقيق مجموعة من المهام. يحدد كل طاقم استراتيجية تنفيذ المهام وتعاون الوكلاء وسير العمل العام. + +## خصائص الطاقم + +| الخاصية | المعامل | الوصف | +| :------------------------------------ | :--------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **المهام** | `tasks` | قائمة المهام المعيّنة للطاقم. | +| **الوكلاء** | `agents` | قائمة الوكلاء الذين يشكلون جزءًا من الطاقم. | +| **العملية** _(اختياري)_ | `process` | تدفق العملية (مثل تسلسلي، هرمي) الذي يتبعه الطاقم. الافتراضي `sequential`. | +| **الوضع المفصل** _(اختياري)_ | `verbose` | مستوى التفصيل في التسجيل أثناء التنفيذ. الافتراضي `False`. | +| **LLM المدير** _(اختياري)_ | `manager_llm` | نموذج اللغة المستخدم بواسطة وكيل المدير في العملية الهرمية. **مطلوب عند استخدام العملية الهرمية.** | +| **LLM استدعاء الدوال** _(اختياري)_ | `function_calling_llm` | إذا مُرر، سيستخدم الطاقم هذا LLM لاستدعاء دوال الأدوات لجميع الوكلاء. يمكن لكل وكيل أن يكون له LLM خاص يتجاوز LLM الطاقم. | +| **التهيئة** _(اختياري)_ | `config` | إعدادات تهيئة اختيارية للطاقم، بتنسيق `Json` أو `Dict[str, Any]`. | +| **الحد الأقصى لـ RPM** _(اختياري)_ | `max_rpm` | الحد الأقصى للطلبات في الدقيقة. الافتراضي `None`. | +| **الذاكرة** _(اختياري)_ | `memory` | تُستخدم لتخزين ذاكرات التنفيذ (قصيرة المدى، طويلة المدى، ذاكرة الكيانات). | +| **التخزين المؤقت** _(اختياري)_ | `cache` | يحدد ما إذا كان يُستخدم تخزين مؤقت لنتائج تنفيذ الأدوات. الافتراضي `True`. | +| **المُضمّن** _(اختياري)_ | `embedder` | تهيئة المُضمّن المستخدم من قبل الطاقم. الافتراضي `{"provider": "openai"}`. | +| **دالة الخطوة** _(اختياري)_ | `step_callback` | دالة تُستدعى بعد كل خطوة لكل وكيل. | +| **دالة المهمة** _(اختياري)_ | `task_callback` | دالة تُستدعى بعد اكتمال كل مهمة. | +| **مشاركة الطاقم** _(اختياري)_ | `share_crew` | ما إذا كنت تريد مشاركة معلومات الطاقم الكاملة وتنفيذه مع فريق CrewAI. | +| **ملف سجل المخرجات** _(اختياري)_ | `output_log_file` | عيّن True لحفظ السجلات كـ logs.txt أو وفّر مسار ملف. الافتراضي `None`. | +| **وكيل المدير** _(اختياري)_ | `manager_agent` | يعيّن وكيلًا مخصصًا سيُستخدم كمدير. | +| **التخطيط** *(اختياري)* | `planning` | يضيف قدرة التخطيط للطاقم. | +| **LLM التخطيط** *(اختياري)* | `planning_llm` | نموذج اللغة المستخدم بواسطة AgentPlanner في عملية التخطيط. | +| **مصادر المعرفة** _(اختياري)_ | `knowledge_sources` | مصادر المعرفة المتاحة على مستوى الطاقم، يمكن لجميع الوكلاء الوصول إليها. | +| **البث** _(اختياري)_ | `stream` | تفعيل مخرجات البث لتلقي تحديثات في الوقت الفعلي. الافتراضي `False`. | + + +**الحد الأقصى لـ RPM للطاقم**: تعيّن خاصية `max_rpm` الحد الأقصى للطلبات في الدقيقة التي يمكن للطاقم تنفيذها لتجنب حدود المعدل وستتجاوز إعدادات `max_rpm` الفردية للوكلاء إذا عيّنتها. + + +## إنشاء الأطقم + +هناك طريقتان لإنشاء الأطقم في CrewAI: باستخدام **تهيئة YAML (موصى بها)** أو تعريفها **مباشرة في الكود**. + +### تهيئة YAML (موصى بها) + +توفر تهيئة YAML طريقة أنظف وأكثر قابلية للصيانة لتعريف الأطقم وتتسق مع كيفية تعريف الوكلاء والمهام في مشاريع CrewAI. + +```python code +from crewai import Agent, Crew, Task, Process +from crewai.project import CrewBase, agent, task, crew, before_kickoff, after_kickoff +from crewai.agents.agent_builder.base_agent import BaseAgent +from typing import List + +@CrewBase +class YourCrewName: + """Description of your crew""" + + agents: List[BaseAgent] + tasks: List[Task] + + agents_config = 'config/agents.yaml' + tasks_config = 'config/tasks.yaml' + + @before_kickoff + def prepare_inputs(self, inputs): + inputs['additional_data'] = "Some extra information" + return inputs + + @after_kickoff + def process_output(self, output): + output.raw += "\nProcessed after kickoff." + return output + + @agent + def agent_one(self) -> Agent: + return Agent( + config=self.agents_config['agent_one'], # type: ignore[index] + verbose=True + ) + + @task + def task_one(self) -> Task: + return Task( + config=self.tasks_config['task_one'] # type: ignore[index] + ) + + @crew + def crew(self) -> Crew: + return Crew( + agents=self.agents, + tasks=self.tasks, + process=Process.sequential, + verbose=True, + ) +``` + + +سيتم تنفيذ المهام بالترتيب الذي عُرّفت به. + + +فئة `CrewBase`، مع هذه المزيّنات، تؤتمت جمع الوكلاء والمهام، مما يقلل الحاجة للإدارة اليدوية. + +### تعريف مباشر في الكود (بديل) + +بدلاً من ذلك، يمكنك تعريف الطاقم مباشرة في الكود بدون ملفات تهيئة YAML. + +## مخرجات الطاقم + +تُغلّف مخرجات الطاقم في فئة `CrewOutput`. توفر هذه الفئة طريقة منظمة للوصول إلى نتائج تنفيذ الطاقم، بما في ذلك تنسيقات متنوعة مثل السلاسل النصية الخام وJSON ونماذج Pydantic. + +### خصائص مخرجات الطاقم + +| الخاصية | المعامل | النوع | الوصف | +| :--------------- | :------------- | :------------------------- | :--------------------------------------------------------------------------------------------------- | +| **Raw** | `raw` | `str` | المخرجات الخام للطاقم. هذا هو التنسيق الافتراضي. | +| **Pydantic** | `pydantic` | `Optional[BaseModel]` | كائن نموذج Pydantic يمثل المخرجات المنظمة. | +| **JSON Dict** | `json_dict` | `Optional[Dict[str, Any]]` | قاموس يمثل مخرجات JSON. | +| **Tasks Output** | `tasks_output` | `List[TaskOutput]` | قائمة كائنات `TaskOutput`، كل منها يمثل مخرجات مهمة. | +| **Token Usage** | `token_usage` | `Dict[str, Any]` | ملخص استخدام الرموز. | + +## استخدام الذاكرة + +يمكن للأطقم استخدام الذاكرة (قصيرة المدى، طويلة المدى، وذاكرة الكيانات) لتحسين تنفيذها وتعلمها بمرور الوقت. + +## استخدام التخزين المؤقت + +يمكن استخدام التخزين المؤقت لتخزين نتائج تنفيذ الأدوات، مما يجعل العملية أكثر كفاءة. + +## مقاييس استخدام الطاقم + +بعد تنفيذ الطاقم، يمكنك الوصول إلى خاصية `usage_metrics` لعرض مقاييس استخدام نموذج اللغة (LLM) لجميع المهام المنفذة. + +```python Code +crew = Crew(agents=[agent1, agent2], tasks=[task1, task2]) +crew.kickoff() +print(crew.usage_metrics) +``` + +## عملية تنفيذ الطاقم + +- **العملية التسلسلية**: تُنفذ المهام واحدة تلو الأخرى، مما يسمح بتدفق عمل خطي. +- **العملية الهرمية**: ينسق وكيل مدير الطاقم، ويفوّض المهام ويتحقق من النتائج. + +### تشغيل الطاقم + +بمجرد تجميع طاقمك، ابدأ سير العمل بطريقة `kickoff()`. + +```python Code +result = my_crew.kickoff() +print(result) +``` + +### طرق مختلفة لتشغيل الطاقم + +#### الطرق المتزامنة + +- `kickoff()`: يبدأ عملية التنفيذ وفقًا لتدفق العملية المحدد. +- `kickoff_for_each()`: ينفذ المهام بالتتابع لكل مدخل. + +#### الطرق غير المتزامنة + +| الطريقة | النوع | الوصف | +|--------|------|-------------| +| `akickoff()` | غير متزامن أصلي | async/await أصلي عبر سلسلة التنفيذ بأكملها | +| `akickoff_for_each()` | غير متزامن أصلي | تنفيذ غير متزامن أصلي لكل مدخل في قائمة | +| `kickoff_async()` | مبني على الخيوط | يغلّف التنفيذ المتزامن في `asyncio.to_thread` | +| `kickoff_for_each_async()` | مبني على الخيوط | غير متزامن مبني على الخيوط لكل مدخل في قائمة | + + +لأحمال العمل عالية التزامن، يُوصى بـ `akickoff()` و `akickoff_for_each()` لأنها تستخدم async أصلي. + + +### بث تنفيذ الطاقم + +للرؤية في الوقت الفعلي لتنفيذ الطاقم، يمكنك تفعيل البث: + +```python Code +crew = Crew( + agents=[researcher], + tasks=[task], + stream=True +) + +streaming = crew.kickoff(inputs={"topic": "AI"}) +for chunk in streaming: + print(chunk.content, end="", flush=True) + +result = streaming.result +``` + +### الإعادة من مهمة محددة + +يمكنك الآن الإعادة من مهمة محددة باستخدام أمر CLI `replay`. + +```shell +crewai log-tasks-outputs +``` + +ثم للإعادة من مهمة محددة: + +```shell +crewai replay -t +``` diff --git a/docs/ar/concepts/event-listener.mdx b/docs/ar/concepts/event-listener.mdx new file mode 100644 index 000000000..41be56cb8 --- /dev/null +++ b/docs/ar/concepts/event-listener.mdx @@ -0,0 +1,236 @@ +--- +title: "مستمعو الأحداث" +description: "الاستفادة من أحداث CrewAI لبناء تكاملات مخصصة ومراقبة" +icon: spinner +mode: "wide" +--- + +## نظرة عامة + +يوفر CrewAI نظام أحداث قوي يتيح لك الاستماع والتفاعل مع الأحداث المختلفة التي تحدث أثناء تنفيذ طاقمك. تُمكّنك هذه الميزة من بناء تكاملات مخصصة وحلول مراقبة وأنظمة تسجيل أو أي وظائف أخرى تحتاج للتشغيل بناءً على أحداث CrewAI الداخلية. + +## كيف يعمل + +يستخدم CrewAI بنية ناقل أحداث لإرسال الأحداث طوال دورة حياة التنفيذ. يُبنى نظام الأحداث على المكونات التالية: + +1. **CrewAIEventsBus**: ناقل أحداث فريد يدير تسجيل الأحداث وإرسالها +2. **BaseEvent**: الفئة الأساسية لجميع الأحداث في النظام +3. **BaseEventListener**: فئة أساسية مجردة لإنشاء مستمعي أحداث مخصصين + +عندما تحدث إجراءات محددة في CrewAI (مثل بدء تنفيذ طاقم، أو إكمال وكيل لمهمة، أو استخدام أداة)، يرسل النظام أحداثًا مقابلة. يمكنك تسجيل معالجات لهذه الأحداث لتنفيذ كود مخصص عند حدوثها. + + +يوفر CrewAI AMP ميزة تتبع أوامر مدمجة تستفيد من نظام الأحداث لتتبع وتخزين وتصور جميع الأوامر والاستكمالات والبيانات الوصفية المرتبطة. + +![Prompt Tracing Dashboard](/images/enterprise/traces-overview.png) + +مع تتبع الأوامر يمكنك: + +- عرض السجل الكامل لجميع الأوامر المرسلة إلى LLM +- تتبع استخدام الرموز والتكاليف +- تصحيح إخفاقات استدلال الوكيل +- مشاركة تسلسلات الأوامر مع فريقك +- مقارنة استراتيجيات الأوامر المختلفة +- تصدير التتبعات للامتثال والتدقيق + + +## إنشاء مستمع أحداث مخصص + +لإنشاء مستمع أحداث مخصص، تحتاج إلى: + +1. إنشاء فئة ترث من `BaseEventListener` +2. تنفيذ طريقة `setup_listeners` +3. تسجيل معالجات للأحداث التي تهمك +4. إنشاء مثيل من مستمعك في الملف المناسب + +إليك مثالًا بسيطًا: + +```python +from crewai.events import ( + CrewKickoffStartedEvent, + CrewKickoffCompletedEvent, + AgentExecutionCompletedEvent, +) +from crewai.events import BaseEventListener + +class MyCustomListener(BaseEventListener): + def __init__(self): + super().__init__() + + def setup_listeners(self, crewai_event_bus): + @crewai_event_bus.on(CrewKickoffStartedEvent) + def on_crew_started(source, event): + print(f"Crew '{event.crew_name}' has started execution!") + + @crewai_event_bus.on(CrewKickoffCompletedEvent) + def on_crew_completed(source, event): + print(f"Crew '{event.crew_name}' has completed execution!") + print(f"Output: {event.output}") + + @crewai_event_bus.on(AgentExecutionCompletedEvent) + def on_agent_execution_completed(source, event): + print(f"Agent '{event.agent.role}' completed task") + print(f"Output: {event.output}") +``` + +## تسجيل المستمع بشكل صحيح + +مجرد تعريف فئة المستمع ليس كافيًا. تحتاج لإنشاء مثيل منه والتأكد من استيراده في تطبيقك. + +```python +# في ملف crew.py +from crewai import Agent, Crew, Task +from my_listeners import MyCustomListener + +# إنشاء مثيل من المستمع +my_listener = MyCustomListener() + +class MyCustomCrew: + def crew(self): + return Crew( + agents=[...], + tasks=[...], + ) +``` + +## أنواع الأحداث المتاحة + +يوفر CrewAI مجموعة واسعة من الأحداث يمكنك الاستماع إليها: + +### أحداث الطاقم + +- **CrewKickoffStartedEvent**: يُرسل عند بدء تنفيذ الطاقم +- **CrewKickoffCompletedEvent**: يُرسل عند اكتمال تنفيذ الطاقم +- **CrewKickoffFailedEvent**: يُرسل عند فشل تنفيذ الطاقم +- **CrewTestStartedEvent**: يُرسل عند بدء اختبار الطاقم +- **CrewTestCompletedEvent**: يُرسل عند اكتمال اختبار الطاقم +- **CrewTestFailedEvent**: يُرسل عند فشل اختبار الطاقم +- **CrewTrainStartedEvent**: يُرسل عند بدء تدريب الطاقم +- **CrewTrainCompletedEvent**: يُرسل عند اكتمال تدريب الطاقم +- **CrewTrainFailedEvent**: يُرسل عند فشل تدريب الطاقم + +### أحداث الوكيل + +- **AgentExecutionStartedEvent**: يُرسل عند بدء تنفيذ وكيل لمهمة +- **AgentExecutionCompletedEvent**: يُرسل عند اكتمال تنفيذ وكيل لمهمة +- **AgentExecutionErrorEvent**: يُرسل عند مواجهة وكيل لخطأ أثناء التنفيذ +- **LiteAgentExecutionStartedEvent**: يُرسل عند بدء تنفيذ LiteAgent +- **LiteAgentExecutionCompletedEvent**: يُرسل عند اكتمال تنفيذ LiteAgent + +### أحداث المهام + +- **TaskStartedEvent**: يُرسل عند بدء تنفيذ مهمة +- **TaskCompletedEvent**: يُرسل عند اكتمال تنفيذ مهمة +- **TaskFailedEvent**: يُرسل عند فشل تنفيذ مهمة + +### أحداث استخدام الأدوات + +- **ToolUsageStartedEvent**: يُرسل عند بدء تنفيذ أداة +- **ToolUsageFinishedEvent**: يُرسل عند اكتمال تنفيذ أداة +- **ToolUsageErrorEvent**: يُرسل عند مواجهة خطأ في تنفيذ أداة + +### أحداث MCP + +- **MCPConnectionStartedEvent**: يُرسل عند بدء الاتصال بخادم MCP +- **MCPConnectionCompletedEvent**: يُرسل عند اكتمال الاتصال بخادم MCP +- **MCPConnectionFailedEvent**: يُرسل عند فشل الاتصال بخادم MCP +- **MCPToolExecutionStartedEvent**: يُرسل عند بدء تنفيذ أداة MCP +- **MCPToolExecutionCompletedEvent**: يُرسل عند اكتمال تنفيذ أداة MCP +- **MCPToolExecutionFailedEvent**: يُرسل عند فشل تنفيذ أداة MCP + +### أحداث المعرفة + +- **KnowledgeRetrievalStartedEvent**: يُرسل عند بدء استرجاع المعرفة +- **KnowledgeRetrievalCompletedEvent**: يُرسل عند اكتمال استرجاع المعرفة +- **KnowledgeQueryStartedEvent**: يُرسل عند بدء استعلام المعرفة +- **KnowledgeQueryCompletedEvent**: يُرسل عند اكتمال استعلام المعرفة +- **KnowledgeQueryFailedEvent**: يُرسل عند فشل استعلام المعرفة + +### أحداث حواجز LLM + +- **LLMGuardrailStartedEvent**: يُرسل عند بدء التحقق من الحاجز +- **LLMGuardrailCompletedEvent**: يُرسل عند اكتمال التحقق من الحاجز +- **LLMGuardrailFailedEvent**: يُرسل عند فشل التحقق من الحاجز + +### أحداث التدفق + +- **FlowCreatedEvent**: يُرسل عند إنشاء تدفق +- **FlowStartedEvent**: يُرسل عند بدء تنفيذ تدفق +- **FlowFinishedEvent**: يُرسل عند اكتمال تنفيذ تدفق +- **FlowPausedEvent**: يُرسل عند إيقاف تدفق مؤقتًا بانتظار ملاحظات بشرية + +### أحداث LLM + +- **LLMCallStartedEvent**: يُرسل عند بدء استدعاء LLM +- **LLMCallCompletedEvent**: يُرسل عند اكتمال استدعاء LLM +- **LLMCallFailedEvent**: يُرسل عند فشل استدعاء LLM +- **LLMStreamChunkEvent**: يُرسل لكل جزء مستلم أثناء بث استجابات LLM + +### أحداث الذاكرة + +- **MemoryQueryStartedEvent**: يُرسل عند بدء استعلام الذاكرة +- **MemoryQueryCompletedEvent**: يُرسل عند اكتمال استعلام الذاكرة +- **MemorySaveStartedEvent**: يُرسل عند بدء حفظ الذاكرة +- **MemorySaveCompletedEvent**: يُرسل عند اكتمال حفظ الذاكرة + +### أحداث الاستدلال + +- **AgentReasoningStartedEvent**: يُرسل عند بدء وكيل الاستدلال حول مهمة +- **AgentReasoningCompletedEvent**: يُرسل عند انتهاء عملية الاستدلال +- **AgentReasoningFailedEvent**: يُرسل عند فشل عملية الاستدلال + +### أحداث A2A (وكيل إلى وكيل) + +- **A2ADelegationStartedEvent**: يُرسل عند بدء تفويض A2A +- **A2ADelegationCompletedEvent**: يُرسل عند اكتمال تفويض A2A +- **A2AConversationStartedEvent**: يُرسل عند بدء محادثة A2A متعددة الأدوار +- **A2AConversationCompletedEvent**: يُرسل عند انتهاء محادثة A2A + +## هيكل معالج الأحداث + +يستقبل كل معالج حدث معاملين: + +1. **source**: الكائن الذي أرسل الحدث +2. **event**: مثيل الحدث، يحتوي على بيانات خاصة بالحدث + +هيكل كائن الحدث يعتمد على نوع الحدث، لكن جميع الأحداث ترث من `BaseEvent` وتتضمن: + +- **timestamp**: الوقت الذي أُرسل فيه الحدث +- **type**: معرّف نصي لنوع الحدث + +## الاستخدام المتقدم: المعالجات المحددة النطاق + +لمعالجة الأحداث المؤقتة، يمكنك استخدام مدير سياق `scoped_handlers`: + +```python +from crewai.events import crewai_event_bus, CrewKickoffStartedEvent + +with crewai_event_bus.scoped_handlers(): + @crewai_event_bus.on(CrewKickoffStartedEvent) + def temp_handler(source, event): + print("This handler only exists within this context") + + # قم بشيء يرسل أحداثًا + +# خارج السياق، يتم إزالة المعالج المؤقت +``` + +## حالات الاستخدام + +يمكن استخدام مستمعي الأحداث لأغراض متنوعة: + +1. **التسجيل والمراقبة**: تتبع تنفيذ طاقمك وتسجيل الأحداث المهمة +2. **التحليلات**: جمع بيانات عن أداء وسلوك طاقمك +3. **التصحيح**: إعداد مستمعين مؤقتين لتصحيح مشاكل محددة +4. **التكامل**: ربط CrewAI بأنظمة خارجية مثل منصات المراقبة وقواعد البيانات أو خدمات الإشعارات +5. **السلوك المخصص**: تشغيل إجراءات مخصصة بناءً على أحداث محددة + +## أفضل الممارسات + +1. **اجعل المعالجات خفيفة**: يجب أن تكون معالجات الأحداث خفيفة وتتجنب العمليات الحاجبة +2. **معالجة الأخطاء**: أدرج معالجة أخطاء مناسبة في معالجات الأحداث لمنع الاستثناءات من التأثير على التنفيذ الرئيسي +3. **التنظيف**: إذا خصص مستمعك موارد، تأكد من تنظيفها بشكل صحيح +4. **الاستماع الانتقائي**: استمع فقط للأحداث التي تحتاج فعلاً لمعالجتها +5. **الاختبار**: اختبر مستمعي الأحداث بمعزل لضمان سلوكهم كما هو متوقع + +بالاستفادة من نظام أحداث CrewAI، يمكنك توسيع وظائفه ودمجه بسلاسة مع بنيتك التحتية الحالية. diff --git a/docs/ar/concepts/files.mdx b/docs/ar/concepts/files.mdx new file mode 100644 index 000000000..66516a093 --- /dev/null +++ b/docs/ar/concepts/files.mdx @@ -0,0 +1,267 @@ +--- +title: الملفات +description: تمرير الصور وملفات PDF والصوت والفيديو والنصوص إلى وكلائك للمعالجة متعددة الوسائط. +icon: file-image +--- + +## نظرة عامة + +يدعم CrewAI مدخلات الملفات متعددة الوسائط الأصلية، مما يتيح لك تمرير الصور وملفات PDF والصوت والفيديو والنصوص مباشرة إلى وكلائك. يتم تنسيق الملفات تلقائيًا وفقًا لمتطلبات API لكل مزود LLM. + + +يتطلب دعم الملفات حزمة `crewai-files` الاختيارية. ثبّتها بـ: + +```bash +uv add 'crewai[file-processing]' +``` + + + +واجهة معالجة الملفات حاليًا في مرحلة الوصول المبكر. + + +## أنواع الملفات + +يدعم CrewAI خمسة أنواع ملفات محددة بالإضافة إلى فئة `File` العامة التي تكتشف النوع تلقائيًا: + +| النوع | الفئة | حالات الاستخدام | +|:-----|:------|:----------| +| **صورة** | `ImageFile` | صور، لقطات شاشة، مخططات، رسوم بيانية | +| **PDF** | `PDFFile` | مستندات، تقارير، أوراق بحثية | +| **صوت** | `AudioFile` | تسجيلات صوتية، بودكاست، اجتماعات | +| **فيديو** | `VideoFile` | تسجيلات شاشة، عروض تقديمية | +| **نص** | `TextFile` | ملفات كود، سجلات، ملفات بيانات | +| **عام** | `File` | اكتشاف تلقائي للنوع من المحتوى | + +```python +from crewai_files import File, ImageFile, PDFFile, AudioFile, VideoFile, TextFile + +image = ImageFile(source="screenshot.png") +pdf = PDFFile(source="report.pdf") +audio = AudioFile(source="meeting.mp3") +video = VideoFile(source="demo.mp4") +text = TextFile(source="data.csv") + +file = File(source="document.pdf") +``` + +## مصادر الملفات + +يقبل معامل `source` أنواع إدخال متعددة ويكتشف تلقائيًا المعالج المناسب: + +### من مسار + +```python +from crewai_files import ImageFile + +image = ImageFile(source="./images/chart.png") +``` + +### من عنوان URL + +```python +from crewai_files import ImageFile + +image = ImageFile(source="https://example.com/image.png") +``` + +### من بايتات + +```python +from crewai_files import ImageFile, FileBytes + +image_bytes = download_image_from_api() +image = ImageFile(source=FileBytes(data=image_bytes, filename="downloaded.png")) +image = ImageFile(source=image_bytes) +``` + +## استخدام الملفات + +يمكن تمرير الملفات على مستويات متعددة، حيث تأخذ المستويات الأكثر تحديدًا الأولوية. + +### مع الأطقم + +مرر الملفات عند تشغيل طاقم: + +```python +from crewai import Crew +from crewai_files import ImageFile + +crew = Crew(agents=[analyst], tasks=[analysis_task]) + +result = crew.kickoff( + inputs={"topic": "Q4 Sales"}, + input_files={ + "chart": ImageFile(source="sales_chart.png"), + "report": PDFFile(source="quarterly_report.pdf"), + } +) +``` + +### مع المهام + +أرفق الملفات بمهام محددة: + +```python +from crewai import Task +from crewai_files import ImageFile + +task = Task( + description="Analyze the sales chart and identify trends in {chart}", + expected_output="A summary of key trends", + input_files={ + "chart": ImageFile(source="sales_chart.png"), + } +) +``` + +### مع التدفقات + +مرر الملفات إلى التدفقات، والتي تنتقل تلقائيًا إلى الأطقم: + +```python +from crewai.flow.flow import Flow, start +from crewai_files import ImageFile + +class AnalysisFlow(Flow): + @start() + def analyze(self): + return self.analysis_crew.kickoff() + +flow = AnalysisFlow() +result = flow.kickoff( + input_files={"image": ImageFile(source="data.png")} +) +``` + +### مع الوكلاء المستقلين + +مرر الملفات مباشرة إلى تشغيل الوكيل: + +```python +from crewai import Agent +from crewai_files import ImageFile + +agent = Agent( + role="Image Analyst", + goal="Analyze images", + backstory="Expert at visual analysis", + llm="gpt-4o", +) + +result = agent.kickoff( + messages="What's in this image?", + input_files={"photo": ImageFile(source="photo.jpg")}, +) +``` + +## أولوية الملفات + +عند تمرير الملفات على مستويات متعددة، تتجاوز المستويات الأكثر تحديدًا المستويات الأوسع: + +``` +Flow input_files < Crew input_files < Task input_files +``` + +على سبيل المثال، إذا عرّف كل من التدفق والمهمة ملفًا باسم `"chart"`، تُستخدم نسخة المهمة. + +## دعم المزودين + +تدعم المزودات المختلفة أنواع ملفات مختلفة. يقوم CrewAI تلقائيًا بتنسيق الملفات وفقًا لواجهة كل مزود. + +| المزود | صورة | PDF | صوت | فيديو | نص | +|:---------|:-----:|:---:|:-----:|:-----:|:----:| +| **OpenAI** (completions API) | ✓ | | | | | +| **OpenAI** (responses API) | ✓ | ✓ | ✓ | | | +| **Anthropic** (claude-3.x) | ✓ | ✓ | | | | +| **Google Gemini** (gemini-1.5, 2.0, 2.5) | ✓ | ✓ | ✓ | ✓ | ✓ | +| **AWS Bedrock** (claude-3) | ✓ | ✓ | | | | +| **Azure OpenAI** (gpt-4o) | ✓ | | ✓ | | | + + +تدعم نماذج Google Gemini جميع أنواع الملفات بما في ذلك الفيديو (حتى ساعة واحدة، 2 جيجابايت). استخدم Gemini عندما تحتاج لمعالجة محتوى الفيديو. + + + +إذا مررت نوع ملف لا يدعمه المزود (مثل الفيديو إلى OpenAI)، ستتلقى خطأ `UnsupportedFileTypeError`. اختر مزودك بناءً على أنواع الملفات التي تحتاج لمعالجتها. + + +## كيف تُرسل الملفات + +يختار CrewAI تلقائيًا الطريقة المثلى لإرسال الملفات إلى كل مزود: + +| الطريقة | الوصف | متى تُستخدم | +|:-------|:------------|:----------| +| **Inline Base64** | الملف مضمّن مباشرة في الطلب | ملفات صغيرة (< 5 ميجابايت عادة) | +| **File Upload API** | الملف يُرفع بشكل منفصل، يُشار إليه بمعرّف | ملفات كبيرة تتجاوز العتبة | +| **URL Reference** | عنوان URL مباشر يُمرر إلى النموذج | مصدر الملف هو عنوان URL بالفعل | + +### طرق الإرسال حسب المزود + +| المزود | Inline Base64 | File Upload API | URL References | +|:---------|:-------------:|:---------------:|:--------------:| +| **OpenAI** | ✓ | ✓ (> 5 MB) | ✓ | +| **Anthropic** | ✓ | ✓ (> 5 MB) | ✓ | +| **Google Gemini** | ✓ | ✓ (> 20 MB) | ✓ | +| **AWS Bedrock** | ✓ | | ✓ (S3 URIs) | +| **Azure OpenAI** | ✓ | | ✓ | + + +لا تحتاج لإدارة هذا بنفسك. يستخدم CrewAI تلقائيًا الطريقة الأكثر كفاءة بناءً على حجم الملف وقدرات المزود. المزودات بدون واجهات رفع الملفات تستخدم inline base64 لجميع الملفات. + + +## أوضاع معالجة الملفات + +تحكم في كيفية معالجة الملفات عندما تتجاوز حدود المزود: + +```python +from crewai_files import ImageFile, PDFFile + +image = ImageFile(source="large.png", mode="strict") +image = ImageFile(source="large.png", mode="auto") +image = ImageFile(source="large.png", mode="warn") +pdf = PDFFile(source="large.pdf", mode="chunk") +``` + +## قيود المزودين + +لكل مزود حدود محددة لأحجام الملفات والأبعاد: + +### OpenAI +- **الصور**: حد أقصى 20 ميجابايت، حتى 10 صور لكل طلب +- **PDF**: حد أقصى 32 ميجابايت، حتى 100 صفحة +- **الصوت**: حد أقصى 25 ميجابايت، حتى 25 دقيقة + +### Anthropic +- **الصور**: حد أقصى 5 ميجابايت، أقصى 8000x8000 بكسل، حتى 100 صورة +- **PDF**: حد أقصى 32 ميجابايت، حتى 100 صفحة + +### Google Gemini +- **الصور**: حد أقصى 100 ميجابايت +- **PDF**: حد أقصى 50 ميجابايت +- **الصوت**: حد أقصى 100 ميجابايت، حتى 9.5 ساعة +- **الفيديو**: حد أقصى 2 جيجابايت، حتى ساعة واحدة + +### AWS Bedrock +- **الصور**: حد أقصى 4.5 ميجابايت، أقصى 8000x8000 بكسل +- **PDF**: حد أقصى 3.75 ميجابايت، حتى 100 صفحة + +## الإشارة إلى الملفات في الأوامر + +استخدم اسم مفتاح الملف في أوصاف المهام للإشارة إلى الملفات: + +```python +task = Task( + description=""" + Analyze the provided materials: + 1. Review the chart in {sales_chart} + 2. Cross-reference with data in {quarterly_report} + 3. Summarize key findings + """, + expected_output="Analysis summary with key insights", + input_files={ + "sales_chart": ImageFile(source="chart.png"), + "quarterly_report": PDFFile(source="report.pdf"), + } +) +``` diff --git a/docs/ar/concepts/flows.mdx b/docs/ar/concepts/flows.mdx new file mode 100644 index 000000000..8c01bdd97 --- /dev/null +++ b/docs/ar/concepts/flows.mdx @@ -0,0 +1,1068 @@ +--- +title: التدفقات +description: تعلّم كيفية إنشاء وإدارة سير عمل الذكاء الاصطناعي باستخدام تدفقات CrewAI. +icon: arrow-progress +mode: "wide" +--- + +## نظرة عامة + +تدفقات CrewAI هي ميزة قوية مصممة لتبسيط إنشاء وإدارة سير عمل الذكاء الاصطناعي. تتيح التدفقات للمطورين دمج وتنسيق مهام البرمجة وفرق Crew بكفاءة، مما يوفر إطار عمل متين لبناء أتمتة ذكاء اصطناعي متطورة. + +تتيح لك التدفقات إنشاء سير عمل منظم يعتمد على الأحداث. فهي توفر طريقة سلسة لربط مهام متعددة وإدارة الحالة والتحكم في تدفق التنفيذ في تطبيقات الذكاء الاصطناعي الخاصة بك. باستخدام التدفقات، يمكنك بسهولة تصميم وتنفيذ عمليات متعددة الخطوات تستفيد من الإمكانيات الكاملة لـ CrewAI. + +1. **تبسيط إنشاء سير العمل**: ربط فرق Crew والمهام المتعددة بسهولة لإنشاء سير عمل ذكاء اصطناعي معقد. + +2. **إدارة الحالة**: تجعل التدفقات إدارة ومشاركة الحالة بين المهام المختلفة في سير العمل أمرًا سهلًا للغاية. + +3. **بنية تعتمد على الأحداث**: مبنية على نموذج يعتمد على الأحداث، مما يتيح سير عمل ديناميكي وسريع الاستجابة. + +4. **تحكم مرن في التدفق**: تنفيذ المنطق الشرطي والحلقات والتفرع ضمن سير العمل. + +## البدء + +لنقم بإنشاء تدفق بسيط حيث ستستخدم OpenAI لإنشاء مدينة عشوائية في مهمة واحدة ثم استخدام تلك المدينة لإنشاء حقيقة ممتعة في مهمة أخرى. + +```python Code + +from crewai.flow.flow import Flow, listen, start +from dotenv import load_dotenv +from litellm import completion + + +class ExampleFlow(Flow): + model = "gpt-4o-mini" + + @start() + def generate_city(self): + print("Starting flow") + # Each flow state automatically gets a unique ID + print(f"Flow State ID: {self.state['id']}") + + response = completion( + model=self.model, + messages=[ + { + "role": "user", + "content": "Return the name of a random city in the world.", + }, + ], + ) + + random_city = response["choices"][0]["message"]["content"] + # Store the city in our state + self.state["city"] = random_city + print(f"Random City: {random_city}") + + return random_city + + @listen(generate_city) + def generate_fun_fact(self, random_city): + response = completion( + model=self.model, + messages=[ + { + "role": "user", + "content": f"Tell me a fun fact about {random_city}", + }, + ], + ) + + fun_fact = response["choices"][0]["message"]["content"] + # Store the fun fact in our state + self.state["fun_fact"] = fun_fact + return fun_fact + + + +flow = ExampleFlow() +flow.plot() +result = flow.kickoff() + +print(f"Generated fun fact: {result}") +``` +![Flow Visual image](/images/crewai-flow-1.png) +في المثال أعلاه، أنشأنا تدفقًا بسيطًا يولّد مدينة عشوائية باستخدام OpenAI ثم يولّد حقيقة ممتعة عن تلك المدينة. يتكون التدفق من مهمتين: `generate_city` و `generate_fun_fact`. مهمة `generate_city` هي نقطة البداية للتدفق، ومهمة `generate_fun_fact` تستمع لمخرجات مهمة `generate_city`. + +يتلقى كل مثيل من التدفق تلقائيًا معرّفًا فريدًا (UUID) في حالته، مما يساعد في تتبع وإدارة عمليات تنفيذ التدفق. يمكن للحالة أيضًا تخزين بيانات إضافية (مثل المدينة المولّدة والحقيقة الممتعة) التي تستمر طوال تنفيذ التدفق. + +عند تشغيل التدفق، سيقوم بما يلي: +1. توليد معرّف فريد لحالة التدفق +2. توليد مدينة عشوائية وتخزينها في الحالة +3. توليد حقيقة ممتعة عن تلك المدينة وتخزينها في الحالة +4. طباعة النتائج في وحدة التحكم + +يمكن أن يكون المعرّف الفريد للحالة والبيانات المخزّنة مفيدًا لتتبع عمليات تنفيذ التدفق والحفاظ على السياق بين المهام. + +**ملاحظة:** تأكد من إعداد ملف `.env` لتخزين `OPENAI_API_KEY` الخاص بك. هذا المفتاح ضروري للمصادقة على طلبات OpenAI API. + +### @start() + +يحدد المزخرف `@start()` نقاط الدخول للتدفق. يمكنك: + +- تعريف عدة نقاط بداية غير مشروطة: `@start()` +- ربط البداية بدالة سابقة أو تسمية موجّه: `@start("method_or_label")` +- توفير شرط قابل للاستدعاء للتحكم في وقت تنفيذ البداية + +جميع دوال `@start()` المستوفية للشروط ستُنفَّذ (غالبًا بالتوازي) عند بدء أو استئناف التدفق. + +### @listen() + +يُستخدم المزخرف `@listen()` لتحديد دالة كمستمع لمخرجات مهمة أخرى في التدفق. ستُنفَّذ الدالة المزخرفة بـ `@listen()` عندما تُصدر المهمة المحددة مخرجاتها. يمكن للدالة الوصول إلى مخرجات المهمة التي تستمع إليها كمعامل. + +#### الاستخدام + +يمكن استخدام المزخرف `@listen()` بعدة طرق: + +1. **الاستماع لدالة بالاسم**: يمكنك تمرير اسم الدالة التي تريد الاستماع إليها كسلسلة نصية. عند اكتمال تلك الدالة، سيتم تشغيل دالة المستمع. + + ```python Code + @listen("generate_city") + def generate_fun_fact(self, random_city): + # Implementation + ``` + +2. **الاستماع لدالة مباشرة**: يمكنك تمرير الدالة نفسها. عند اكتمال تلك الدالة، سيتم تشغيل دالة المستمع. + ```python Code + @listen(generate_city) + def generate_fun_fact(self, random_city): + # Implementation + ``` + +### مخرجات التدفق + +الوصول إلى مخرجات التدفق والتعامل معها أمر أساسي لدمج سير عمل الذكاء الاصطناعي في التطبيقات أو الأنظمة الأكبر. توفر تدفقات CrewAI آليات مباشرة لاسترداد المخرجات النهائية والوصول إلى النتائج الوسيطة وإدارة الحالة العامة للتدفق. + +#### استرداد المخرجات النهائية + +عند تشغيل تدفق، يتم تحديد المخرجات النهائية بواسطة آخر دالة تكتمل. تُعيد دالة `kickoff()` مخرجات هذه الدالة الأخيرة. + +إليك كيفية الوصول إلى المخرجات النهائية: + + +```python Code +from crewai.flow.flow import Flow, listen, start + +class OutputExampleFlow(Flow): + @start() + def first_method(self): + return "Output from first_method" + + @listen(first_method) + def second_method(self, first_output): + return f"Second method received: {first_output}" + + +flow = OutputExampleFlow() +flow.plot("my_flow_plot") +final_output = flow.kickoff() + +print("---- Final Output ----") +print(final_output) +``` + +```text Output +---- Final Output ---- +Second method received: Output from first_method +``` + + +![Flow Visual image](/images/crewai-flow-2.png) + +في هذا المثال، `second_method` هي آخر دالة تكتمل، لذا ستكون مخرجاتها هي المخرجات النهائية للتدفق. +ستُعيد دالة `kickoff()` المخرجات النهائية، التي تُطبع بعد ذلك في وحدة التحكم. ستولّد دالة `plot()` ملف HTML الذي سيساعدك على فهم التدفق. + +#### الوصول إلى الحالة وتحديثها + +بالإضافة إلى استرداد المخرجات النهائية، يمكنك أيضًا الوصول إلى الحالة وتحديثها داخل التدفق. يمكن استخدام الحالة لتخزين ومشاركة البيانات بين الدوال المختلفة في التدفق. بعد تشغيل التدفق، يمكنك الوصول إلى الحالة لاسترداد أي معلومات تمت إضافتها أو تحديثها أثناء التنفيذ. + +إليك مثال على كيفية تحديث الحالة والوصول إليها: + + + +```python Code +from crewai.flow.flow import Flow, listen, start +from pydantic import BaseModel + +class ExampleState(BaseModel): + counter: int = 0 + message: str = "" + +class StateExampleFlow(Flow[ExampleState]): + + @start() + def first_method(self): + self.state.message = "Hello from first_method" + self.state.counter += 1 + + @listen(first_method) + def second_method(self): + self.state.message += " - updated by second_method" + self.state.counter += 1 + return self.state.message + +flow = StateExampleFlow() +flow.plot("my_flow_plot") +final_output = flow.kickoff() +print(f"Final Output: {final_output}") +print("Final State:") +print(flow.state) +``` + +```text Output +Final Output: Hello from first_method - updated by second_method +Final State: +counter=2 message='Hello from first_method - updated by second_method' +``` + + + +![Flow Visual image](/images/crewai-flow-2.png) + +في هذا المثال، يتم تحديث الحالة بواسطة كل من `first_method` و `second_method`. +بعد تشغيل التدفق، يمكنك الوصول إلى الحالة النهائية لرؤية التحديثات التي أجرتها هذه الدوال. + +من خلال ضمان إعادة مخرجات الدالة الأخيرة وتوفير الوصول إلى الحالة، تجعل تدفقات CrewAI من السهل دمج نتائج سير عمل الذكاء الاصطناعي في التطبيقات أو الأنظمة الأكبر، +مع الحفاظ على الوصول إلى الحالة طوال تنفيذ التدفق. + +## إدارة حالة التدفق + +إدارة الحالة بفعالية أمر بالغ الأهمية لبناء سير عمل ذكاء اصطناعي موثوق وقابل للصيانة. توفر تدفقات CrewAI آليات قوية لإدارة الحالة غير المهيكلة والمهيكلة، +مما يتيح للمطورين اختيار النهج الأنسب لاحتياجات تطبيقاتهم. + +### إدارة الحالة غير المهيكلة + +في إدارة الحالة غير المهيكلة، يتم تخزين جميع الحالات في خاصية `state` لفئة `Flow`. +يوفر هذا النهج مرونة، مما يمكّن المطورين من إضافة أو تعديل خصائص الحالة أثناء التشغيل دون تحديد مخطط صارم. +حتى مع الحالات غير المهيكلة، تولّد تدفقات CrewAI تلقائيًا معرّفًا فريدًا (UUID) لكل مثيل حالة وتحافظ عليه. + +```python Code +from crewai.flow.flow import Flow, listen, start + +class UnstructuredExampleFlow(Flow): + + @start() + def first_method(self): + # The state automatically includes an 'id' field + print(f"State ID: {self.state['id']}") + self.state['counter'] = 0 + self.state['message'] = "Hello from structured flow" + + @listen(first_method) + def second_method(self): + self.state['counter'] += 1 + self.state['message'] += " - updated" + + @listen(second_method) + def third_method(self): + self.state['counter'] += 1 + self.state['message'] += " - updated again" + + print(f"State after third_method: {self.state}") + + +flow = UnstructuredExampleFlow() +flow.plot("my_flow_plot") +flow.kickoff() +``` + +![Flow Visual image](/images/crewai-flow-3.png) + +**ملاحظة:** يتم توليد حقل `id` تلقائيًا والحفاظ عليه طوال تنفيذ التدفق. لا تحتاج إلى إدارته أو تعيينه يدويًا، وسيتم الحفاظ عليه حتى عند تحديث الحالة ببيانات جديدة. + +**النقاط الرئيسية:** + +- **المرونة:** يمكنك إضافة خصائص ديناميكيًا إلى `self.state` دون قيود محددة مسبقًا. +- **البساطة:** مثالي لسير العمل البسيط حيث يكون هيكل الحالة بسيطًا أو متغيرًا بشكل كبير. + +### إدارة الحالة المهيكلة + +تستفيد إدارة الحالة المهيكلة من مخططات محددة مسبقًا لضمان الاتساق وسلامة الأنواع عبر سير العمل. +باستخدام نماذج مثل `BaseModel` من Pydantic، يمكن للمطورين تحديد الشكل الدقيق للحالة، مما يتيح تحققًا أفضل وإكمالًا تلقائيًا في بيئات التطوير. + +تتلقى كل حالة في تدفقات CrewAI تلقائيًا معرّفًا فريدًا (UUID) للمساعدة في تتبع وإدارة مثيلات الحالة. يتم توليد هذا المعرّف وإدارته تلقائيًا بواسطة نظام التدفق. + +```python Code +from crewai.flow.flow import Flow, listen, start +from pydantic import BaseModel + + +class ExampleState(BaseModel): + # Note: 'id' field is automatically added to all states + counter: int = 0 + message: str = "" + + +class StructuredExampleFlow(Flow[ExampleState]): + + @start() + def first_method(self): + # Access the auto-generated ID if needed + print(f"State ID: {self.state.id}") + self.state.message = "Hello from structured flow" + + @listen(first_method) + def second_method(self): + self.state.counter += 1 + self.state.message += " - updated" + + @listen(second_method) + def third_method(self): + self.state.counter += 1 + self.state.message += " - updated again" + + print(f"State after third_method: {self.state}") + + +flow = StructuredExampleFlow() +flow.kickoff() +``` + +![Flow Visual image](/images/crewai-flow-3.png) + +**النقاط الرئيسية:** + +- **مخطط محدد:** يحدد `ExampleState` هيكل الحالة بوضوح، مما يعزز قابلية قراءة الكود وصيانته. +- **سلامة الأنواع:** يضمن استخدام Pydantic التزام خصائص الحالة بالأنواع المحددة، مما يقلل من أخطاء وقت التشغيل. +- **الإكمال التلقائي:** يمكن لبيئات التطوير المتكاملة توفير إكمال تلقائي أفضل وفحص أخطاء بناءً على نموذج الحالة المحدد. + +### الاختيار بين إدارة الحالة غير المهيكلة والمهيكلة + +- **استخدم إدارة الحالة غير المهيكلة عندما:** + + - يكون حالة سير العمل بسيطة أو ديناميكية للغاية. + - تكون المرونة أولوية على تعريفات الحالة الصارمة. + - يكون النماذج الأولية السريعة مطلوبة دون عبء تحديد المخططات. + +- **استخدم إدارة الحالة المهيكلة عندما:** + - يتطلب سير العمل هيكل حالة محدد جيدًا ومتسق. + - تكون سلامة الأنواع والتحقق مهمتين لموثوقية تطبيقك. + - تريد الاستفادة من ميزات بيئة التطوير المتكاملة مثل الإكمال التلقائي وفحص الأنواع لتجربة مطور أفضل. + +من خلال توفير خيارات إدارة الحالة غير المهيكلة والمهيكلة، تمكّن تدفقات CrewAI المطورين من بناء سير عمل ذكاء اصطناعي مرن ومتين في آن واحد، ملبيةً مجموعة واسعة من متطلبات التطبيقات. + +## استمرارية التدفق + +يتيح مزخرف @persist الاستمرارية التلقائية للحالة في تدفقات CrewAI، مما يسمح لك بالحفاظ على حالة التدفق عبر عمليات إعادة التشغيل أو تنفيذات سير العمل المختلفة. يمكن تطبيق هذا المزخرف على مستوى الفئة أو مستوى الدالة، مما يوفر مرونة في كيفية إدارة استمرارية الحالة. + +### الاستمرارية على مستوى الفئة + +عند التطبيق على مستوى الفئة، يقوم مزخرف @persist باستمرارية حالات جميع دوال التدفق تلقائيًا: + +```python +@persist # Using SQLiteFlowPersistence by default +class MyFlow(Flow[MyState]): + @start() + def initialize_flow(self): + # This method will automatically have its state persisted + self.state.counter = 1 + print("Initialized flow. State ID:", self.state.id) + + @listen(initialize_flow) + def next_step(self): + # The state (including self.state.id) is automatically reloaded + self.state.counter += 1 + print("Flow state is persisted. Counter:", self.state.counter) +``` + +### الاستمرارية على مستوى الدالة + +للتحكم الأكثر دقة، يمكنك تطبيق @persist على دوال محددة: + +```python +class AnotherFlow(Flow[dict]): + @persist # Persists only this method's state + @start() + def begin(self): + if "runs" not in self.state: + self.state["runs"] = 0 + self.state["runs"] += 1 + print("Method-level persisted runs:", self.state["runs"]) +``` + +### كيف تعمل + +1. **تعريف الحالة الفريد** + - تتلقى كل حالة تدفق UUID فريد تلقائيًا + - يتم الحفاظ على المعرّف عبر تحديثات الحالة واستدعاءات الدوال + - يدعم كلًا من الحالات المهيكلة (Pydantic BaseModel) وغير المهيكلة (القاموس) + +2. **واجهة SQLite الافتراضية** + - SQLiteFlowPersistence هي واجهة التخزين الافتراضية + - يتم حفظ الحالات تلقائيًا في قاعدة بيانات SQLite محلية + - معالجة أخطاء متينة تضمن رسائل واضحة في حالة فشل عمليات قاعدة البيانات + +3. **معالجة الأخطاء** + - رسائل خطأ شاملة لعمليات قاعدة البيانات + - تحقق تلقائي من الحالة أثناء الحفظ والتحميل + - ملاحظات واضحة عند مواجهة مشاكل في عمليات الاستمرارية + +### اعتبارات مهمة + +- **أنواع الحالة**: يتم دعم كل من الحالات المهيكلة (Pydantic BaseModel) وغير المهيكلة (القاموس) +- **المعرّف التلقائي**: يتم إضافة حقل `id` تلقائيًا إذا لم يكن موجودًا +- **استعادة الحالة**: يمكن للتدفقات الفاشلة أو المُعاد تشغيلها إعادة تحميل حالتها السابقة تلقائيًا +- **التنفيذ المخصص**: يمكنك توفير تنفيذ FlowPersistence الخاص بك لاحتياجات التخزين المتخصصة + +### المزايا التقنية + +1. **تحكم دقيق من خلال الوصول المنخفض المستوى** + - وصول مباشر لعمليات الاستمرارية لحالات الاستخدام المتقدمة + - تحكم دقيق عبر مزخرفات الاستمرارية على مستوى الدوال + - قدرات مدمجة لفحص الحالة وتصحيح الأخطاء + - رؤية كاملة لتغييرات الحالة وعمليات الاستمرارية + +2. **موثوقية معززة** + - استعادة تلقائية للحالة بعد أعطال النظام أو إعادة التشغيل + - تحديثات حالة قائمة على المعاملات لسلامة البيانات + - معالجة أخطاء شاملة مع رسائل خطأ واضحة + - تحقق متين أثناء عمليات حفظ وتحميل الحالة + +3. **بنية قابلة للتوسع** + - واجهة استمرارية قابلة للتخصيص من خلال واجهة FlowPersistence + - دعم لحلول تخزين متخصصة تتجاوز SQLite + - متوافقة مع كل من الحالات المهيكلة (Pydantic) وغير المهيكلة (dict) + - تكامل سلس مع أنماط تدفق CrewAI الحالية + +تركز بنية نظام الاستمرارية على الدقة التقنية وخيارات التخصيص، مما يتيح للمطورين الحفاظ على التحكم الكامل في إدارة الحالة مع الاستفادة من ميزات الموثوقية المدمجة. + +## التحكم في التدفق + +### المنطق الشرطي: `or` + +تتيح لك دالة `or_` في التدفقات الاستماع لعدة دوال وتشغيل دالة المستمع عندما تُصدر أي من الدوال المحددة مخرجاتها. + + + +```python Code +from crewai.flow.flow import Flow, listen, or_, start + +class OrExampleFlow(Flow): + + @start() + def start_method(self): + return "Hello from the start method" + + @listen(start_method) + def second_method(self): + return "Hello from the second method" + + @listen(or_(start_method, second_method)) + def logger(self, result): + print(f"Logger: {result}") + + + +flow = OrExampleFlow() +flow.plot("my_flow_plot") +flow.kickoff() +``` + +```text Output +Logger: Hello from the start method +Logger: Hello from the second method +``` + + + +![Flow Visual image](/images/crewai-flow-4.png) + +عند تشغيل هذا التدفق، سيتم تشغيل دالة `logger` بواسطة مخرجات إما `start_method` أو `second_method`. +تُستخدم دالة `or_` للاستماع لعدة دوال وتشغيل دالة المستمع عندما تُصدر أي من الدوال المحددة مخرجاتها. + +### المنطق الشرطي: `and` + +تتيح لك دالة `and_` في التدفقات الاستماع لعدة دوال وتشغيل دالة المستمع فقط عندما تُصدر جميع الدوال المحددة مخرجاتها. + + + +```python Code +from crewai.flow.flow import Flow, and_, listen, start + +class AndExampleFlow(Flow): + + @start() + def start_method(self): + self.state["greeting"] = "Hello from the start method" + + @listen(start_method) + def second_method(self): + self.state["joke"] = "What do computers eat? Microchips." + + @listen(and_(start_method, second_method)) + def logger(self): + print("---- Logger ----") + print(self.state) + +flow = AndExampleFlow() +flow.plot() +flow.kickoff() +``` + +```text Output +---- Logger ---- +{'greeting': 'Hello from the start method', 'joke': 'What do computers eat? Microchips.'} +``` + + + +![Flow Visual image](/images/crewai-flow-5.png) + +عند تشغيل هذا التدفق، سيتم تشغيل دالة `logger` فقط عندما يُصدر كل من `start_method` و `second_method` مخرجاتهما. +تُستخدم دالة `and_` للاستماع لعدة دوال وتشغيل دالة المستمع فقط عندما تُصدر جميع الدوال المحددة مخرجاتها. + +### الموجّه + +يتيح لك مزخرف `@router()` في التدفقات تحديد منطق توجيه شرطي بناءً على مخرجات دالة. +يمكنك تحديد مسارات مختلفة بناءً على مخرجات الدالة، مما يتيح لك التحكم في تدفق التنفيذ ديناميكيًا. + + + +```python Code +import random +from crewai.flow.flow import Flow, listen, router, start +from pydantic import BaseModel + +class ExampleState(BaseModel): + success_flag: bool = False + +class RouterFlow(Flow[ExampleState]): + + @start() + def start_method(self): + print("Starting the structured flow") + random_boolean = random.choice([True, False]) + self.state.success_flag = random_boolean + + @router(start_method) + def second_method(self): + if self.state.success_flag: + return "success" + else: + return "failed" + + @listen("success") + def third_method(self): + print("Third method running") + + @listen("failed") + def fourth_method(self): + print("Fourth method running") + + +flow = RouterFlow() +flow.plot("my_flow_plot") +flow.kickoff() +``` + +```text Output +Starting the structured flow +Third method running +Fourth method running +``` + + + +![Flow Visual image](/images/crewai-flow-6.png) + +في المثال أعلاه، تولّد `start_method` قيمة منطقية عشوائية وتعيّنها في الحالة. +تستخدم `second_method` مزخرف `@router()` لتحديد منطق توجيه شرطي بناءً على قيمة المنطقية. +إذا كانت القيمة `True`، تُعيد الدالة `"success"`، وإذا كانت `False`، تُعيد `"failed"`. +تستمع `third_method` و `fourth_method` لمخرجات `second_method` وتُنفَّذ بناءً على القيمة المُعادة. + +عند تشغيل هذا التدفق، ستتغير المخرجات بناءً على القيمة المنطقية العشوائية المولّدة بواسطة `start_method`. + +### الإنسان في الحلقة (التغذية الراجعة البشرية) + + +يتطلب مزخرف `@human_feedback` **CrewAI الإصدار 1.8.0 أو أعلى**. + + +يتيح مزخرف `@human_feedback` سير عمل يتضمن تدخلًا بشريًا من خلال إيقاف تنفيذ التدفق مؤقتًا لجمع تغذية راجعة من إنسان. هذا مفيد لبوابات الموافقة ومراجعة الجودة ونقاط القرار التي تتطلب حكمًا بشريًا. + +```python Code +from crewai.flow.flow import Flow, start, listen +from crewai.flow.human_feedback import human_feedback, HumanFeedbackResult + +class ReviewFlow(Flow): + @start() + @human_feedback( + message="Do you approve this content?", + emit=["approved", "rejected", "needs_revision"], + llm="gpt-4o-mini", + default_outcome="needs_revision", + ) + def generate_content(self): + return "Content to be reviewed..." + + @listen("approved") + def on_approval(self, result: HumanFeedbackResult): + print(f"Approved! Feedback: {result.feedback}") + + @listen("rejected") + def on_rejection(self, result: HumanFeedbackResult): + print(f"Rejected. Reason: {result.feedback}") +``` + +عند تحديد `emit`، يتم تفسير التغذية الراجعة الحرة للإنسان بواسطة LLM وتُختصر إلى إحدى النتائج المحددة، والتي تُشغل بعد ذلك مزخرف `@listen` المقابل. + +يمكنك أيضًا استخدام `@human_feedback` دون توجيه لجمع التغذية الراجعة ببساطة: + +```python Code +@start() +@human_feedback(message="Any comments on this output?") +def my_method(self): + return "Output for review" + +@listen(my_method) +def next_step(self, result: HumanFeedbackResult): + # Access feedback via result.feedback + # Access original output via result.output + pass +``` + +يمكنك الوصول إلى جميع التغذيات الراجعة المُجمّعة أثناء التدفق عبر `self.last_human_feedback` (الأحدث) أو `self.human_feedback_history` (جميع التغذيات الراجعة كقائمة). + +للحصول على دليل كامل حول التغذية الراجعة البشرية في التدفقات، بما في ذلك **التغذية الراجعة غير المتزامنة/غير الحاجبة** مع مزودين مخصصين (Slack، webhooks، إلخ)، انظر [التغذية الراجعة البشرية في التدفقات](/ar/learn/human-feedback-in-flows). + +## إضافة Agents إلى التدفقات + +يمكن دمج Agents بسلاسة في تدفقاتك، مما يوفر بديلًا خفيف الوزن لفرق Crew الكاملة عندما تحتاج إلى تنفيذ مهام أبسط وأكثر تركيزًا. إليك مثال على كيفية استخدام Agent ضمن تدفق لإجراء أبحاث السوق: + +```python +import asyncio +from typing import Any, Dict, List + +from crewai_tools import SerperDevTool +from pydantic import BaseModel, Field + +from crewai.agent import Agent +from crewai.flow.flow import Flow, listen, start + + +# Define a structured output format +class MarketAnalysis(BaseModel): + key_trends: List[str] = Field(description="List of identified market trends") + market_size: str = Field(description="Estimated market size") + competitors: List[str] = Field(description="Major competitors in the space") + + +# Define flow state +class MarketResearchState(BaseModel): + product: str = "" + analysis: MarketAnalysis | None = None + + +# Create a flow class +class MarketResearchFlow(Flow[MarketResearchState]): + @start() + def initialize_research(self) -> Dict[str, Any]: + print(f"Starting market research for {self.state.product}") + return {"product": self.state.product} + + @listen(initialize_research) + async def analyze_market(self) -> Dict[str, Any]: + # Create an Agent for market research + analyst = Agent( + role="Market Research Analyst", + goal=f"Analyze the market for {self.state.product}", + backstory="You are an experienced market analyst with expertise in " + "identifying market trends and opportunities.", + tools=[SerperDevTool()], + verbose=True, + ) + + # Define the research query + query = f""" + Research the market for {self.state.product}. Include: + 1. Key market trends + 2. Market size + 3. Major competitors + + Format your response according to the specified structure. + """ + + # Execute the analysis with structured output format + result = await analyst.kickoff_async(query, response_format=MarketAnalysis) + if result.pydantic: + print("result", result.pydantic) + else: + print("result", result) + + # Return the analysis to update the state + return {"analysis": result.pydantic} + + @listen(analyze_market) + def present_results(self, analysis) -> None: + print("\nMarket Analysis Results") + print("=====================") + + if isinstance(analysis, dict): + # If we got a dict with 'analysis' key, extract the actual analysis object + market_analysis = analysis.get("analysis") + else: + market_analysis = analysis + + if market_analysis and isinstance(market_analysis, MarketAnalysis): + print("\nKey Market Trends:") + for trend in market_analysis.key_trends: + print(f"- {trend}") + + print(f"\nMarket Size: {market_analysis.market_size}") + + print("\nMajor Competitors:") + for competitor in market_analysis.competitors: + print(f"- {competitor}") + else: + print("No structured analysis data available.") + print("Raw analysis:", analysis) + + +# Usage example +async def run_flow(): + flow = MarketResearchFlow() + flow.plot("MarketResearchFlowPlot") + result = await flow.kickoff_async(inputs={"product": "AI-powered chatbots"}) + return result + + +# Run the flow +if __name__ == "__main__": + asyncio.run(run_flow()) +``` + +![Flow Visual image](/images/crewai-flow-7.png) + +يوضح هذا المثال عدة ميزات رئيسية لاستخدام Agents في التدفقات: + +1. **المخرجات المهيكلة**: استخدام نماذج Pydantic لتحديد تنسيق المخرجات المتوقع (`MarketAnalysis`) يضمن سلامة الأنواع والبيانات المهيكلة في جميع أنحاء التدفق. + +2. **إدارة الحالة**: تحافظ حالة التدفق (`MarketResearchState`) على السياق بين الخطوات وتخزّن كلًا من المدخلات والمخرجات. + +3. **تكامل الأدوات**: يمكن لـ Agents استخدام أدوات (مثل `WebsiteSearchTool`) لتعزيز قدراتهم. + +## إضافة فرق Crew إلى التدفقات + +إنشاء تدفق مع فرق Crew متعددة في CrewAI أمر مباشر. + +يمكنك إنشاء مشروع CrewAI جديد يتضمن جميع الهيكلية اللازمة لإنشاء تدفق مع فرق Crew متعددة عن طريق تشغيل الأمر التالي: + +```bash +crewai create flow name_of_flow +``` + +سيولّد هذا الأمر مشروع CrewAI جديد مع هيكل المجلدات اللازم. يتضمن المشروع المولّد فريق Crew مُعد مسبقًا يُسمى `poem_crew` ويعمل بالفعل. يمكنك استخدام هذا الفريق كقالب بنسخه ولصقه وتعديله لإنشاء فرق أخرى. + +### هيكل المجلدات + +بعد تشغيل أمر `crewai create flow name_of_flow`، سترى هيكل مجلدات مشابه للتالي: + +| المجلد/الملف | الوصف | +| :--------------------- | :----------------------------------------------------------------- | +| `name_of_flow/` | المجلد الجذر للتدفق. | +| ├── `crews/` | يحتوي على مجلدات لفرق Crew المحددة. | +| │ └── `poem_crew/` | مجلد لـ "poem_crew" مع إعداداته وسكربتاته. | +| │ ├── `config/` | مجلد ملفات الإعداد لـ "poem_crew". | +| │ │ ├── `agents.yaml` | ملف YAML يحدد الـ Agents لـ "poem_crew". | +| │ │ └── `tasks.yaml` | ملف YAML يحدد المهام لـ "poem_crew". | +| │ ├── `poem_crew.py` | سكربت وظائف "poem_crew". | +| ├── `tools/` | مجلد للأدوات الإضافية المُستخدمة في التدفق. | +| │ └── `custom_tool.py` | تنفيذ أداة مخصصة. | +| ├── `main.py` | السكربت الرئيسي لتشغيل التدفق. | +| ├── `README.md` | وصف المشروع والتعليمات. | +| ├── `pyproject.toml` | ملف إعداد تبعيات المشروع والإعدادات. | +| └── `.gitignore` | يحدد الملفات والمجلدات المراد تجاهلها في التحكم بالإصدارات. | + +### بناء فرق Crew الخاصة بك + +في مجلد `crews`، يمكنك تحديد فرق Crew متعددة. سيكون لكل فريق مجلده الخاص الذي يحتوي على ملفات الإعداد وملف تعريف الفريق. على سبيل المثال، يحتوي مجلد `poem_crew` على: + +- `config/agents.yaml`: يحدد الـ Agents للفريق. +- `config/tasks.yaml`: يحدد المهام للفريق. +- `poem_crew.py`: يحتوي على تعريف الفريق، بما في ذلك الـ Agents والمهام والفريق نفسه. + +يمكنك نسخ ولصق وتعديل `poem_crew` لإنشاء فرق أخرى. + +### ربط فرق Crew في `main.py` + +ملف `main.py` هو حيث تنشئ التدفق وتربط فرق Crew معًا. يمكنك تحديد التدفق باستخدام فئة `Flow` والمزخرفات `@start` و `@listen` لتحديد تدفق التنفيذ. + +إليك مثال على كيفية ربط `poem_crew` في ملف `main.py`: + +```python Code +#!/usr/bin/env python +from random import randint + +from pydantic import BaseModel +from crewai.flow.flow import Flow, listen, start +from .crews.poem_crew.poem_crew import PoemCrew + + +class PoemState(BaseModel): + sentence_count: int = 1 + poem: str = "" + +class PoemFlow(Flow[PoemState]): + + @start() + def generate_sentence_count(self): + print("Generating sentence count") + self.state.sentence_count = randint(1, 5) + + @listen(generate_sentence_count) + def generate_poem(self): + print("Generating poem") + result = PoemCrew().crew().kickoff(inputs={"sentence_count": self.state.sentence_count}) + + print("Poem generated", result.raw) + self.state.poem = result.raw + + @listen(generate_poem) + def save_poem(self): + print("Saving poem") + with open("poem.txt", "w") as f: + f.write(self.state.poem) + +def kickoff(): + poem_flow = PoemFlow() + poem_flow.kickoff() + + +def plot(): + poem_flow = PoemFlow() + poem_flow.plot("PoemFlowPlot") + +if __name__ == "__main__": + kickoff() + plot() +``` + +في هذا المثال، تحدد فئة `PoemFlow` تدفقًا يولّد عدد الجمل، ويستخدم `PoemCrew` لتوليد قصيدة، ثم يحفظ القصيدة في ملف. يتم بدء التدفق باستدعاء دالة `kickoff()`. سيتم توليد PoemFlowPlot بواسطة دالة `plot()`. + +![Flow Visual image](/images/crewai-flow-8.png) + +### تشغيل التدفق + +(اختياري) قبل تشغيل التدفق، يمكنك تثبيت التبعيات بتشغيل: + +```bash +crewai install +``` + +بمجرد تثبيت جميع التبعيات، تحتاج إلى تفعيل البيئة الافتراضية بتشغيل: + +```bash +source .venv/bin/activate +``` + +بعد تفعيل البيئة الافتراضية، يمكنك تشغيل التدفق بتنفيذ أحد الأوامر التالية: + +```bash +crewai flow kickoff +``` + +أو + +```bash +uv run kickoff +``` + +سيُنفَّذ التدفق، ويجب أن ترى المخرجات في وحدة التحكم. + +## رسم التدفقات + +يمكن أن يوفر تصوير سير عمل الذكاء الاصطناعي رؤى قيمة حول هيكل ومسارات تنفيذ تدفقاتك. تقدم CrewAI أداة تصوير قوية تتيح لك إنشاء رسوم بيانية تفاعلية لتدفقاتك، مما يسهّل فهم وتحسين سير عمل الذكاء الاصطناعي. + +### ما هي الرسوم البيانية؟ + +الرسوم البيانية في CrewAI هي تمثيلات بصرية لسير عمل الذكاء الاصطناعي. تعرض المهام المختلفة واتصالاتها وتدفق البيانات بينها. يساعد هذا التصوير في فهم تسلسل العمليات وتحديد الاختناقات وضمان توافق منطق سير العمل مع توقعاتك. + +### كيفية إنشاء رسم بياني + +توفر CrewAI طريقتين مريحتين لإنشاء رسوم بيانية لتدفقاتك: + +#### الخيار 1: استخدام دالة `plot()` + +إذا كنت تعمل مباشرة مع مثيل تدفق، يمكنك إنشاء رسم بياني باستدعاء دالة `plot()` على كائن التدفق. ستُنشئ هذه الدالة ملف HTML يحتوي على الرسم البياني التفاعلي لتدفقك. + +```python Code +# Assuming you have a flow instance +flow.plot("my_flow_plot") +``` + +سيُنشئ هذا ملفًا باسم `my_flow_plot.html` في مجلدك الحالي. يمكنك فتح هذا الملف في متصفح ويب لعرض الرسم البياني التفاعلي. + +#### الخيار 2: استخدام سطر الأوامر + +إذا كنت تعمل ضمن مشروع CrewAI منظم، يمكنك إنشاء رسم بياني باستخدام سطر الأوامر. هذا مفيد بشكل خاص للمشاريع الأكبر حيث تريد تصوير إعداد التدفق بالكامل. + +```bash +crewai flow plot +``` + +سيُنشئ هذا الأمر ملف HTML مع الرسم البياني لتدفقك، مشابهًا لدالة `plot()`. سيتم حفظ الملف في مجلد مشروعك، ويمكنك فتحه في متصفح ويب لاستكشاف التدفق. + +### فهم الرسم البياني + +سيعرض الرسم البياني المولّد عُقدًا تمثل المهام في تدفقك، مع حواف موجّهة تشير إلى تدفق التنفيذ. الرسم البياني تفاعلي، مما يتيح لك التكبير والتصغير والتمرير فوق العقد لرؤية تفاصيل إضافية. + +من خلال تصوير تدفقاتك، يمكنك الحصول على فهم أوضح لهيكل سير العمل، مما يسهّل تصحيح الأخطاء وتحسين عمليات الذكاء الاصطناعي والتواصل بشأنها مع الآخرين. + +### الخلاصة + +رسم تدفقاتك هو ميزة قوية في CrewAI تعزز قدرتك على تصميم وإدارة سير عمل الذكاء الاصطناعي المعقدة. سواء اخترت استخدام دالة `plot()` أو سطر الأوامر، فإن إنشاء الرسوم البيانية سيوفر لك تمثيلًا بصريًا لسير عملك، مما يساعد في التطوير والعرض. + +## الخطوات التالية + +إذا كنت مهتمًا باستكشاف أمثلة إضافية للتدفقات، لدينا مجموعة متنوعة من التوصيات في مستودع الأمثلة. إليك أربعة أمثلة تدفق محددة، كل منها يعرض حالات استخدام فريدة لمساعدتك في مطابقة نوع مشكلتك الحالية مع مثال محدد: + +1. **تدفق الرد التلقائي على البريد الإلكتروني**: يوضح هذا المثال حلقة لا نهائية حيث تعمل مهمة خلفية باستمرار لأتمتة ردود البريد الإلكتروني. إنها حالة استخدام رائعة للمهام التي تحتاج إلى التنفيذ بشكل متكرر دون تدخل يدوي. [عرض المثال](https://github.com/crewAIInc/crewAI-examples/tree/main/email_auto_responder_flow) + +2. **تدفق تقييم العملاء المحتملين**: يعرض هذا التدفق إضافة تغذية راجعة بشرية والتعامل مع فروع شرطية مختلفة باستخدام الموجّه. إنه مثال ممتاز لكيفية دمج اتخاذ القرارات الديناميكية والرقابة البشرية في سير عملك. [عرض المثال](https://github.com/crewAIInc/crewAI-examples/tree/main/lead-score-flow) + +3. **تدفق كتابة كتاب**: يتفوق هذا المثال في ربط فرق Crew متعددة معًا، حيث تُستخدم مخرجات فريق واحد بواسطة فريق آخر. على وجه التحديد، يقوم فريق واحد بوضع مخطط لكتاب كامل، ويقوم فريق آخر بإنشاء فصول بناءً على المخطط. في النهاية، يتم ربط كل شيء لإنتاج كتاب كامل. هذا التدفق مثالي للعمليات المعقدة متعددة الخطوات التي تتطلب تنسيقًا بين مهام مختلفة. [عرض المثال](https://github.com/crewAIInc/crewAI-examples/tree/main/write_a_book_with_flows) + +4. **تدفق مساعد الاجتماعات**: يوضح هذا التدفق كيفية بث حدث واحد لتشغيل إجراءات متابعة متعددة. على سبيل المثال، بعد اكتمال اجتماع، يمكن للتدفق تحديث لوحة Trello وإرسال رسالة Slack وحفظ النتائج. إنه مثال رائع للتعامل مع نتائج متعددة من حدث واحد، مما يجعله مثاليًا لإدارة المهام الشاملة وأنظمة الإشعارات. [عرض المثال](https://github.com/crewAIInc/crewAI-examples/tree/main/meeting_assistant_flow) + +من خلال استكشاف هذه الأمثلة، يمكنك الحصول على رؤى حول كيفية الاستفادة من تدفقات CrewAI لحالات استخدام متنوعة، من أتمتة المهام المتكررة إلى إدارة العمليات المعقدة متعددة الخطوات مع اتخاذ القرارات الديناميكية والتغذية الراجعة البشرية. + +أيضًا، شاهد فيديو YouTube الخاص بنا حول كيفية استخدام التدفقات في CrewAI أدناه! + + + +## تشغيل التدفقات + +هناك طريقتان لتشغيل التدفق: + +### استخدام واجهة Flow API + +يمكنك تشغيل تدفق برمجيًا عن طريق إنشاء مثيل من فئة التدفق واستدعاء دالة `kickoff()`: + +```python +flow = ExampleFlow() +result = flow.kickoff() +``` + +### بث تنفيذ التدفق + +للحصول على رؤية فورية لتنفيذ التدفق، يمكنك تفعيل البث لتلقي المخرجات فور توليدها: + +```python +class StreamingFlow(Flow): + stream = True # Enable streaming + + @start() + def research(self): + # Your flow implementation + pass + +# Iterate over streaming output +flow = StreamingFlow() +streaming = flow.kickoff() +for chunk in streaming: + print(chunk.content, end="", flush=True) + +# Access final result +result = streaming.result +``` + +تعرّف على المزيد حول البث في دليل [بث تنفيذ التدفق](/ar/learn/streaming-flow-execution). + +## الذاكرة في التدفقات + +يتمتع كل تدفق تلقائيًا بإمكانية الوصول إلى نظام [الذاكرة](/concepts/memory) الموحد في CrewAI. يمكنك تخزين الذكريات واسترجاعها واستخراجها مباشرة داخل أي دالة تدفق باستخدام ثلاث دوال مساعدة مدمجة. + +### الدوال المدمجة + +| الدالة | الوصف | +| :--- | :--- | +| `self.remember(content, **kwargs)` | تخزين المحتوى في الذاكرة. تقبل `scope` و `categories` و `metadata` و `importance` اختياريًا. | +| `self.recall(query, **kwargs)` | استرجاع الذكريات ذات الصلة. تقبل `scope` و `categories` و `limit` و `depth` اختياريًا. | +| `self.extract_memories(content)` | تفكيك النص الخام إلى عبارات ذاكرة منفصلة ومستقلة. | + +يتم إنشاء مثيل `Memory()` افتراضي تلقائيًا عند تهيئة التدفق. يمكنك أيضًا تمرير مثيل مخصص: + +```python +from crewai.flow.flow import Flow +from crewai import Memory + +custom_memory = Memory( + recency_weight=0.5, + recency_half_life_days=7, + embedder={"provider": "ollama", "config": {"model_name": "mxbai-embed-large"}}, +) + +flow = MyFlow(memory=custom_memory) +``` + +### مثال: تدفق البحث والتحليل + +```python +from crewai.flow.flow import Flow, listen, start + + +class ResearchAnalysisFlow(Flow): + @start() + def gather_data(self): + # Simulate research findings + findings = ( + "PostgreSQL handles 10k concurrent connections with connection pooling. " + "MySQL caps at around 5k. MongoDB scales horizontally but adds complexity." + ) + + # Extract atomic facts and remember each one + memories = self.extract_memories(findings) + for mem in memories: + self.remember(mem, scope="/research/databases") + + return findings + + @listen(gather_data) + def analyze(self, raw_findings): + # Recall relevant past research (from this run or previous runs) + past = self.recall("database performance and scaling", limit=10, depth="shallow") + + context_lines = [f"- {m.record.content}" for m in past] + context = "\n".join(context_lines) if context_lines else "No prior context." + + return { + "new_findings": raw_findings, + "prior_context": context, + "total_memories": len(past), + } + + +flow = ResearchAnalysisFlow() +result = flow.kickoff() +print(result) +``` + +نظرًا لأن الذاكرة تستمر عبر عمليات التشغيل (مدعومة بـ LanceDB على القرص)، فإن خطوة `analyze` ستستدعي النتائج من عمليات التنفيذ السابقة أيضًا -- مما يتيح تدفقات تتعلم وتراكم المعرفة بمرور الوقت. + +انظر [وثائق الذاكرة](/concepts/memory) لمزيد من التفاصيل حول النطاقات والشرائح والتسجيل المركب وإعداد المُضمِّن والمزيد. + +### استخدام CLI + +بدءًا من الإصدار 0.103.0، يمكنك تشغيل التدفقات باستخدام أمر `crewai run`: + +```shell +crewai run +``` + +يكتشف هذا الأمر تلقائيًا ما إذا كان مشروعك تدفقًا (بناءً على إعداد `type = "flow"` في pyproject.toml الخاص بك) ويشغّله وفقًا لذلك. هذه هي الطريقة الموصى بها لتشغيل التدفقات من سطر الأوامر. + +للتوافق مع الإصدارات السابقة، يمكنك أيضًا استخدام: + +```shell +crewai flow kickoff +``` + +ومع ذلك، فإن أمر `crewai run` هو الطريقة المفضلة الآن لأنه يعمل لكل من فرق Crew والتدفقات. diff --git a/docs/ar/concepts/knowledge.mdx b/docs/ar/concepts/knowledge.mdx new file mode 100644 index 000000000..807e0801e --- /dev/null +++ b/docs/ar/concepts/knowledge.mdx @@ -0,0 +1,1095 @@ +--- +title: المعرفة +description: ما هي المعرفة في CrewAI وكيفية استخدامها. +icon: book +mode: "wide" +--- + +## نظرة عامة + +المعرفة في CrewAI هي نظام قوي يتيح لوكلاء الذكاء الاصطناعي الوصول إلى مصادر المعلومات الخارجية واستخدامها أثناء مهامهم. +فكّر فيها كمنح وكلائك مكتبة مرجعية يمكنهم الرجوع إليها أثناء العمل. + + + الفوائد الرئيسية لاستخدام المعرفة: + - تعزيز الوكلاء بمعلومات خاصة بالمجال + - دعم القرارات ببيانات من العالم الحقيقي + - الحفاظ على السياق عبر المحادثات + - بناء الاستجابات على معلومات واقعية + + +## أمثلة البدء السريع + + +لمصادر المعرفة المستندة إلى الملفات، تأكد من وضع ملفاتك في مجلد `knowledge` في جذر مشروعك. +أيضًا، استخدم المسارات النسبية من مجلد `knowledge` عند إنشاء المصدر. + + +### إعداد عميل المتجه (RAG) + +يوفر CrewAI تجريدًا لعميل RAG محايد بالنسبة للمزود لمتاجر المتجهات. المزود الافتراضي هو ChromaDB، ويتم دعم Qdrant أيضًا. يمكنك التبديل بين المزودين باستخدام أدوات الإعداد. + +المدعوم حاليًا: +- ChromaDB (افتراضي) +- Qdrant + +```python Code +from crewai.rag.config.utils import set_rag_config, get_rag_client, clear_rag_config + +# ChromaDB (default) +from crewai.rag.chromadb.config import ChromaDBConfig +set_rag_config(ChromaDBConfig()) +chromadb_client = get_rag_client() + +# Qdrant +from crewai.rag.qdrant.config import QdrantConfig +set_rag_config(QdrantConfig()) +qdrant_client = get_rag_client() + +# Example operations (same API for any provider) +client = qdrant_client # or chromadb_client +client.create_collection(collection_name="docs") +client.add_documents( + collection_name="docs", + documents=[{"id": "1", "content": "CrewAI enables collaborative AI agents."}], +) +results = client.search(collection_name="docs", query="collaborative agents", limit=3) + +clear_rag_config() # optional reset +``` + +عميل RAG هذا منفصل عن التخزين المدمج في المعرفة. استخدمه عندما تحتاج إلى تحكم مباشر في متجر المتجهات أو خطوط أنابيب استرجاع مخصصة. + +### مثال المعرفة النصية الأساسية + +```python Code +from crewai import Agent, Task, Crew, Process, LLM +from crewai.knowledge.source.string_knowledge_source import StringKnowledgeSource + +# Create a knowledge source +content = "Users name is John. He is 30 years old and lives in San Francisco." +string_source = StringKnowledgeSource(content=content) + +# Create an LLM with a temperature of 0 to ensure deterministic outputs +llm = LLM(model="gpt-4o-mini", temperature=0) + +# Create an agent with the knowledge store +agent = Agent( + role="About User", + goal="You know everything about the user.", + backstory="You are a master at understanding people and their preferences.", + verbose=True, + allow_delegation=False, + llm=llm, +) + +task = Task( + description="Answer the following questions about the user: {question}", + expected_output="An answer to the question.", + agent=agent, +) + +crew = Crew( + agents=[agent], + tasks=[task], + verbose=True, + process=Process.sequential, + knowledge_sources=[string_source], # Enable knowledge by adding the sources here +) + +result = crew.kickoff(inputs={"question": "What city does John live in and how old is he?"}) +``` + +### مثال معرفة محتوى الويب + + + تحتاج إلى تثبيت `docling` لكي يعمل المثال التالي: `uv add docling` + + +```python Code +from crewai import LLM, Agent, Crew, Process, Task +from crewai.knowledge.source.crew_docling_source import CrewDoclingSource + +# Create a knowledge source from web content +content_source = CrewDoclingSource( + file_paths=[ + "https://lilianweng.github.io/posts/2024-11-28-reward-hacking", + "https://lilianweng.github.io/posts/2024-07-07-hallucination", + ], +) + +# Create an LLM with a temperature of 0 to ensure deterministic outputs +llm = LLM(model="gpt-4o-mini", temperature=0) + +# Create an agent with the knowledge store +agent = Agent( + role="About papers", + goal="You know everything about the papers.", + backstory="You are a master at understanding papers and their content.", + verbose=True, + allow_delegation=False, + llm=llm, +) + +task = Task( + description="Answer the following questions about the papers: {question}", + expected_output="An answer to the question.", + agent=agent, +) + +crew = Crew( + agents=[agent], + tasks=[task], + verbose=True, + process=Process.sequential, + knowledge_sources=[content_source], +) + +result = crew.kickoff( + inputs={"question": "What is the reward hacking paper about? Be sure to provide sources."} +) +``` + +## مصادر المعرفة المدعومة + +يدعم CrewAI أنواعًا متعددة من مصادر المعرفة جاهزة للاستخدام: + + + + - سلاسل نصية خام + - ملفات نصية (.txt) + - مستندات PDF + + + - ملفات CSV + - جداول بيانات Excel + - مستندات JSON + + + +### مصدر معرفة الملفات النصية +```python +from crewai.knowledge.source.text_file_knowledge_source import TextFileKnowledgeSource + +text_source = TextFileKnowledgeSource( + file_paths=["document.txt", "another.txt"] +) +``` + +### مصدر معرفة PDF +```python +from crewai.knowledge.source.pdf_knowledge_source import PDFKnowledgeSource + +pdf_source = PDFKnowledgeSource( + file_paths=["document.pdf", "another.pdf"] +) +``` + +### مصدر معرفة CSV +```python +from crewai.knowledge.source.csv_knowledge_source import CSVKnowledgeSource + +csv_source = CSVKnowledgeSource( + file_paths=["data.csv"] +) +``` + +### مصدر معرفة Excel +```python +from crewai.knowledge.source.excel_knowledge_source import ExcelKnowledgeSource + +excel_source = ExcelKnowledgeSource( + file_paths=["spreadsheet.xlsx"] +) +``` + +### مصدر معرفة JSON +```python +from crewai.knowledge.source.json_knowledge_source import JSONKnowledgeSource + +json_source = JSONKnowledgeSource( + file_paths=["data.json"] +) +``` + + + يُرجى التأكد من إنشاء مجلد ./knowledge. يجب وضع جميع ملفات المصادر (مثل .txt و .pdf و .xlsx و .json) في هذا المجلد للإدارة المركزية. + + +## معرفة Agent مقابل معرفة Crew: دليل شامل + + +**فهم مستويات المعرفة**: يدعم CrewAI المعرفة على مستوى كل من Agent و Crew. يوضح هذا القسم بالضبط كيف يعمل كل منهما، ومتى يتم تهيئتهما، ويعالج المفاهيم الخاطئة الشائعة حول التبعيات. + + +### كيف تعمل تهيئة المعرفة فعليًا + +إليك ما يحدث بالضبط عند استخدام المعرفة: + +#### معرفة على مستوى Agent (مستقلة) +```python +from crewai import Agent, Task, Crew +from crewai.knowledge.source.string_knowledge_source import StringKnowledgeSource + +# Agent with its own knowledge - NO crew knowledge needed +specialist_knowledge = StringKnowledgeSource( + content="Specialized technical information for this agent only" +) + +specialist_agent = Agent( + role="Technical Specialist", + goal="Provide technical expertise", + backstory="Expert in specialized technical domains", + knowledge_sources=[specialist_knowledge] # Agent-specific knowledge +) + +task = Task( + description="Answer technical questions", + agent=specialist_agent, + expected_output="Technical answer" +) + +# No crew-level knowledge required +crew = Crew( + agents=[specialist_agent], + tasks=[task] +) + +result = crew.kickoff() # Agent knowledge works independently +``` + +#### ما يحدث أثناء `crew.kickoff()` + +عند استدعاء `crew.kickoff()`، إليك التسلسل الدقيق: + +```python +# During kickoff +for agent in self.agents: + agent.crew = self # Agent gets reference to crew + agent.set_knowledge(crew_embedder=self.embedder) # Agent knowledge initialized + agent.create_agent_executor() +``` + +#### استقلالية التخزين + +يستخدم كل مستوى معرفة مجموعات تخزين مستقلة: + +```python +# Agent knowledge storage +agent_collection_name = agent.role # e.g., "Technical Specialist" + +# Crew knowledge storage +crew_collection_name = "crew" + +# Both stored in same ChromaDB instance but different collections +# Path: ~/.local/share/CrewAI/{project}/knowledge/ +# ├── crew/ # Crew knowledge collection +# ├── Technical Specialist/ # Agent knowledge collection +# └── Another Agent Role/ # Another agent's collection +``` + +### أمثلة عملية كاملة + +#### المثال 1: معرفة Agent فقط +```python +from crewai import Agent, Task, Crew +from crewai.knowledge.source.string_knowledge_source import StringKnowledgeSource + +# Agent-specific knowledge +agent_knowledge = StringKnowledgeSource( + content="Agent-specific information that only this agent needs" +) + +agent = Agent( + role="Specialist", + goal="Use specialized knowledge", + backstory="Expert with specific knowledge", + knowledge_sources=[agent_knowledge], + embedder={ # Agent can have its own embedder + "provider": "openai", + "config": {"model": "text-embedding-3-small"} + } +) + +task = Task( + description="Answer using your specialized knowledge", + agent=agent, + expected_output="Answer based on agent knowledge" +) + +# No crew knowledge needed +crew = Crew(agents=[agent], tasks=[task]) +result = crew.kickoff() # Works perfectly +``` + +#### المثال 2: معرفة Agent و Crew معًا +```python +# Crew-wide knowledge (shared by all agents) +crew_knowledge = StringKnowledgeSource( + content="Company policies and general information for all agents" +) + +# Agent-specific knowledge +specialist_knowledge = StringKnowledgeSource( + content="Technical specifications only the specialist needs" +) + +specialist = Agent( + role="Technical Specialist", + goal="Provide technical expertise", + backstory="Technical expert", + knowledge_sources=[specialist_knowledge] # Agent-specific +) + +generalist = Agent( + role="General Assistant", + goal="Provide general assistance", + backstory="General helper" + # No agent-specific knowledge +) + +crew = Crew( + agents=[specialist, generalist], + tasks=[...], + knowledge_sources=[crew_knowledge] # Crew-wide knowledge +) + +# Result: +# - specialist gets: crew_knowledge + specialist_knowledge +# - generalist gets: crew_knowledge only +``` + +#### المثال 3: عدة Agents بمعارف مختلفة +```python +# Different knowledge for different agents +sales_knowledge = StringKnowledgeSource(content="Sales procedures and pricing") +tech_knowledge = StringKnowledgeSource(content="Technical documentation") +support_knowledge = StringKnowledgeSource(content="Support procedures") + +sales_agent = Agent( + role="Sales Representative", + knowledge_sources=[sales_knowledge], + embedder={"provider": "openai", "config": {"model": "text-embedding-3-small"}} +) + +tech_agent = Agent( + role="Technical Expert", + knowledge_sources=[tech_knowledge], + embedder={"provider": "ollama", "config": {"model": "mxbai-embed-large"}} +) + +support_agent = Agent( + role="Support Specialist", + knowledge_sources=[support_knowledge] + # Will use crew embedder as fallback +) + +crew = Crew( + agents=[sales_agent, tech_agent, support_agent], + tasks=[...], + embedder={ # Fallback embedder for agents without their own + "provider": "google-generativeai", + "config": {"model_name": "gemini-embedding-001"} + } +) + +# Each agent gets only their specific knowledge +# Each can use different embedding providers +``` + + +على عكس الاسترجاع من قاعدة بيانات متجهات باستخدام أداة، فإن الوكلاء المُحمّلين مسبقًا بالمعرفة لن يحتاجوا إلى شخصية أو مهمة استرجاع. +ما عليك سوى إضافة مصادر المعرفة ذات الصلة التي يحتاجها Agent أو Crew للعمل. + +يمكن إضافة مصادر المعرفة على مستوى Agent أو Crew. +مصادر المعرفة على مستوى Crew سيستخدمها **جميع الوكلاء** في الفريق. +مصادر المعرفة على مستوى Agent سيستخدمها **الوكيل المحدد** المُحمّل بالمعرفة. + + +## إعداد المعرفة + +يمكنك تهيئة إعداد المعرفة لـ Crew أو Agent. + +```python Code +from crewai.knowledge.knowledge_config import KnowledgeConfig + +knowledge_config = KnowledgeConfig(results_limit=10, score_threshold=0.5) + +agent = Agent( + ... + knowledge_config=knowledge_config +) +``` + + + `results_limit`: هو عدد المستندات ذات الصلة المُعادة. القيمة الافتراضية هي 3. + `score_threshold`: هو الحد الأدنى لدرجة اعتبار المستند ذا صلة. القيمة الافتراضية هي 0.35. + + +## معاملات المعرفة المدعومة + + + قائمة مصادر المعرفة التي توفر المحتوى للتخزين والاستعلام. يمكن أن تشمل ملفات PDF و CSV و Excel و JSON والملفات النصية أو المحتوى النصي. + + + اسم المجموعة التي سيتم تخزين المعرفة فيها. يُستخدم لتحديد مجموعات معرفة مختلفة. القيمة الافتراضية هي "knowledge" إذا لم يتم تحديدها. + + +إعداد تخزين مخصص لإدارة كيفية تخزين المعرفة واسترجاعها. إذا لم يتم تحديده، سيتم إنشاء تخزين افتراضي. + + +## شفافية تخزين المعرفة + + +**فهم تخزين المعرفة**: يخزّن CrewAI مصادر المعرفة تلقائيًا في مجلدات خاصة بالمنصة باستخدام ChromaDB للتخزين المتجهي. فهم هذه المواقع والإعدادات الافتراضية يساعد في النشر في بيئة الإنتاج وتصحيح الأخطاء وإدارة التخزين. + + +### أين يخزّن CrewAI ملفات المعرفة + +بشكل افتراضي، يستخدم CrewAI نفس نظام التخزين مثل الذاكرة، حيث يخزّن المعرفة في مجلدات خاصة بالمنصة: + +#### مواقع التخزين الافتراضية حسب المنصة + +**macOS:** +``` +~/Library/Application Support/CrewAI/{project_name}/ +└── knowledge/ # Knowledge ChromaDB files + ├── chroma.sqlite3 # ChromaDB metadata + ├── {collection_id}/ # Vector embeddings + └── knowledge_{collection}/ # Named collections +``` + +**Linux:** +``` +~/.local/share/CrewAI/{project_name}/ +└── knowledge/ + ├── chroma.sqlite3 + ├── {collection_id}/ + └── knowledge_{collection}/ +``` + +**Windows:** +``` +C:\Users\{username}\AppData\Local\CrewAI\{project_name}\ +└── knowledge\ + ├── chroma.sqlite3 + ├── {collection_id}\ + └── knowledge_{collection}\ +``` + +### معرفة موقع تخزين المعرفة + +لرؤية المكان الذي يخزّن فيه CrewAI ملفات المعرفة بالضبط: + +```python +from crewai.utilities.paths import db_storage_path +import os + +# Get the knowledge storage path +knowledge_path = os.path.join(db_storage_path(), "knowledge") +print(f"Knowledge storage location: {knowledge_path}") + +# List knowledge collections and files +if os.path.exists(knowledge_path): + print("\nKnowledge storage contents:") + for item in os.listdir(knowledge_path): + item_path = os.path.join(knowledge_path, item) + if os.path.isdir(item_path): + print(f"📁 Collection: {item}/") + # Show collection contents + try: + for subitem in os.listdir(item_path): + print(f" └── {subitem}") + except PermissionError: + print(f" └── (permission denied)") + else: + print(f"📄 {item}") +else: + print("No knowledge storage found yet.") +``` + +### التحكم في مواقع تخزين المعرفة + +#### الخيار 1: متغير البيئة (موصى به) +```python +import os +from crewai import Crew + +# Set custom storage location for all CrewAI data +os.environ["CREWAI_STORAGE_DIR"] = "./my_project_storage" + +# All knowledge will now be stored in ./my_project_storage/knowledge/ +crew = Crew( + agents=[...], + tasks=[...], + knowledge_sources=[...] +) +``` + +#### الخيار 2: تخزين معرفة مخصص +```python +from crewai.knowledge.storage.knowledge_storage import KnowledgeStorage +from crewai.knowledge.source.string_knowledge_source import StringKnowledgeSource + +# Create custom storage with specific embedder +custom_storage = KnowledgeStorage( + embedder={ + "provider": "ollama", + "config": {"model": "mxbai-embed-large"} + }, + collection_name="my_custom_knowledge" +) + +# Use with knowledge sources +knowledge_source = StringKnowledgeSource( + content="Your knowledge content here" +) +knowledge_source.storage = custom_storage +``` + +#### الخيار 3: تخزين معرفة خاص بالمشروع +```python +import os +from pathlib import Path + +# Store knowledge in project directory +project_root = Path(__file__).parent +knowledge_dir = project_root / "knowledge_storage" + +os.environ["CREWAI_STORAGE_DIR"] = str(knowledge_dir) + +# Now all knowledge will be stored in your project directory +``` + +### سلوك مزود التضمين الافتراضي + + +**مزود التضمين الافتراضي**: يستخدم CrewAI افتراضيًا تضمينات OpenAI (`text-embedding-3-small`) لتخزين المعرفة، حتى عند استخدام مزودي LLM مختلفين. يمكنك تخصيص هذا بسهولة ليتوافق مع إعدادك. + + +#### فهم السلوك الافتراضي +```python +from crewai import Agent, Crew, LLM +from crewai.knowledge.source.string_knowledge_source import StringKnowledgeSource + +# When using Claude as your LLM... +agent = Agent( + role="Researcher", + goal="Research topics", + backstory="Expert researcher", + llm=LLM(provider="anthropic", model="claude-3-sonnet") # Using Claude +) + +# CrewAI will still use OpenAI embeddings by default for knowledge +# This ensures consistency but may not match your LLM provider preference +knowledge_source = StringKnowledgeSource(content="Research data...") + +crew = Crew( + agents=[agent], + tasks=[...], + knowledge_sources=[knowledge_source] + # Default: Uses OpenAI embeddings even with Claude LLM +) +``` + +#### تخصيص مزودي تضمين المعرفة +```python +# Option 1: Use Voyage AI (recommended by Anthropic for Claude users) +crew = Crew( + agents=[agent], + tasks=[...], + knowledge_sources=[knowledge_source], + embedder={ + "provider": "voyageai", # Recommended for Claude users + "config": { + "api_key": "your-voyage-api-key", + "model": "voyage-3" # or "voyage-3-large" for best quality + } + } +) + +# Option 2: Use local embeddings (no external API calls) +crew = Crew( + agents=[agent], + tasks=[...], + knowledge_sources=[knowledge_source], + embedder={ + "provider": "ollama", + "config": { + "model": "mxbai-embed-large", + "url": "http://localhost:11434/api/embeddings" + } + } +) + +# Option 3: Agent-level embedding customization +agent = Agent( + role="Researcher", + goal="Research topics", + backstory="Expert researcher", + knowledge_sources=[knowledge_source], + embedder={ + "provider": "google-generativeai", + "config": { + "model_name": "gemini-embedding-001", + "api_key": "your-google-key" + } + } +) +``` + +#### إعداد تضمينات Azure OpenAI + +عند استخدام تضمينات Azure OpenAI: +1. تأكد من نشر نموذج التضمين في منصة Azure أولًا +2. ثم تحتاج إلى استخدام الإعداد التالي: + +```python +agent = Agent( + role="Researcher", + goal="Research topics", + backstory="Expert researcher", + knowledge_sources=[knowledge_source], + embedder={ + "provider": "azure", + "config": { + "api_key": "your-azure-api-key", + "model": "text-embedding-ada-002", # change to the model you are using and is deployed in Azure + "api_base": "https://your-azure-endpoint.openai.azure.com/", + "api_version": "2024-02-01" + } + } +) +``` + +## الميزات المتقدمة + +### إعادة صياغة الاستعلام + +ينفذ CrewAI آلية إعادة صياغة استعلام ذكية لتحسين استرجاع المعرفة. عندما يحتاج وكيل إلى البحث في مصادر المعرفة، يتم تحويل موجّه المهمة الخام تلقائيًا إلى استعلام بحث أكثر فعالية. + +#### كيف تعمل إعادة صياغة الاستعلام + +1. عندما ينفذ وكيل مهمة بمصادر معرفة متاحة، يتم تشغيل دالة `_get_knowledge_search_query` +2. يُستخدم LLM الخاص بالوكيل لتحويل موجّه المهمة الأصلي إلى استعلام بحث محسّن +3. يُستخدم هذا الاستعلام المحسّن بعد ذلك لاسترجاع المعلومات ذات الصلة من مصادر المعرفة + +#### فوائد إعادة صياغة الاستعلام + + + + من خلال التركيز على المفاهيم الرئيسية وإزالة المحتوى غير ذي الصلة، تساعد إعادة صياغة الاستعلام في استرجاع معلومات أكثر صلة. + + + تم تصميم الاستعلامات المُعاد صياغتها لتكون أكثر تحديدًا ووعيًا بالسياق لاسترجاع قاعدة بيانات المتجهات. + + + +#### مثال + +```python +# Original task prompt +task_prompt = "Answer the following questions about the user's favorite movies: What movie did John watch last week? Format your answer in JSON." + +# Behind the scenes, this might be rewritten as: +rewritten_query = "What movies did John watch last week?" +``` + +الاستعلام المُعاد صياغته أكثر تركيزًا على الحاجة الأساسية للمعلومات ويزيل التعليمات غير ذات الصلة حول تنسيق المخرجات. + + + هذه الآلية تلقائية بالكامل ولا تتطلب أي إعداد من المستخدمين. يُستخدم LLM الخاص بالوكيل لتنفيذ إعادة صياغة الاستعلام، لذا فإن استخدام LLM أكثر قدرة يمكن أن يحسّن جودة الاستعلامات المُعاد صياغتها. + + +### أحداث المعرفة + +يُصدر CrewAI أحداثًا أثناء عملية استرجاع المعرفة يمكنك الاستماع إليها باستخدام نظام الأحداث. تتيح لك هذه الأحداث مراقبة وتصحيح أخطاء وتحليل كيفية استرجاع المعرفة واستخدامها بواسطة وكلائك. + +#### أحداث المعرفة المتاحة + +- **KnowledgeRetrievalStartedEvent**: يُصدر عندما يبدأ وكيل في استرجاع المعرفة من المصادر +- **KnowledgeRetrievalCompletedEvent**: يُصدر عند اكتمال استرجاع المعرفة، بما في ذلك الاستعلام المُستخدم والمحتوى المُسترجع +- **KnowledgeQueryStartedEvent**: يُصدر عند بدء استعلام مصادر المعرفة +- **KnowledgeQueryCompletedEvent**: يُصدر عند اكتمال الاستعلام بنجاح +- **KnowledgeQueryFailedEvent**: يُصدر عند فشل استعلام مصادر المعرفة +- **KnowledgeSearchQueryFailedEvent**: يُصدر عند فشل استعلام بحث + +#### مثال: مراقبة استرجاع المعرفة + +```python +from crewai.events import ( + KnowledgeRetrievalStartedEvent, + KnowledgeRetrievalCompletedEvent, + BaseEventListener, +) + +class KnowledgeMonitorListener(BaseEventListener): + def setup_listeners(self, crewai_event_bus): + @crewai_event_bus.on(KnowledgeRetrievalStartedEvent) + def on_knowledge_retrieval_started(source, event): + print(f"Agent '{event.agent.role}' started retrieving knowledge") + + @crewai_event_bus.on(KnowledgeRetrievalCompletedEvent) + def on_knowledge_retrieval_completed(source, event): + print(f"Agent '{event.agent.role}' completed knowledge retrieval") + print(f"Query: {event.query}") + print(f"Retrieved {len(event.retrieved_knowledge)} knowledge chunks") + +# Create an instance of your listener +knowledge_monitor = KnowledgeMonitorListener() +``` + +لمزيد من المعلومات حول استخدام الأحداث، انظر وثائق [مستمعي الأحداث](/ar/concepts/event-listener). + +### مصادر المعرفة المخصصة + +يتيح لك CrewAI إنشاء مصادر معرفة مخصصة لأي نوع من البيانات عن طريق توسيع فئة `BaseKnowledgeSource`. لنقم بإنشاء مثال عملي يجلب ويعالج مقالات أخبار الفضاء. + +#### مثال مصدر معرفة أخبار الفضاء + + + +```python Code +from crewai import Agent, Task, Crew, Process, LLM +from crewai.knowledge.source.base_knowledge_source import BaseKnowledgeSource +import requests +from datetime import datetime +from typing import Dict, Any +from pydantic import BaseModel, Field + +class SpaceNewsKnowledgeSource(BaseKnowledgeSource): + """Knowledge source that fetches data from Space News API.""" + + api_endpoint: str = Field(description="API endpoint URL") + limit: int = Field(default=10, description="Number of articles to fetch") + + def load_content(self) -> Dict[Any, str]: + """Fetch and format space news articles.""" + try: + response = requests.get( + f"{self.api_endpoint}?limit={self.limit}" + ) + response.raise_for_status() + + data = response.json() + articles = data.get('results', []) + + formatted_data = self.validate_content(articles) + return {self.api_endpoint: formatted_data} + except Exception as e: + raise ValueError(f"Failed to fetch space news: {str(e)}") + + def validate_content(self, articles: list) -> str: + """Format articles into readable text.""" + formatted = "Space News Articles:\n\n" + for article in articles: + formatted += f""" + Title: {article['title']} + Published: {article['published_at']} + Summary: {article['summary']} + News Site: {article['news_site']} + URL: {article['url']} + -------------------""" + return formatted + + def add(self) -> None: + """Process and store the articles.""" + content = self.load_content() + for _, text in content.items(): + chunks = self._chunk_text(text) + self.chunks.extend(chunks) + + self._save_documents() + +# Create knowledge source +recent_news = SpaceNewsKnowledgeSource( + api_endpoint="https://api.spaceflightnewsapi.net/v4/articles", + limit=10, +) + +# Create specialized agent +space_analyst = Agent( + role="Space News Analyst", + goal="Answer questions about space news accurately and comprehensively", + backstory="""You are a space industry analyst with expertise in space exploration, + satellite technology, and space industry trends. You excel at answering questions + about space news and providing detailed, accurate information.""", + knowledge_sources=[recent_news], + llm=LLM(model="gpt-4", temperature=0.0) +) + +# Create task that handles user questions +analysis_task = Task( + description="Answer this question about space news: {user_question}", + expected_output="A detailed answer based on the recent space news articles", + agent=space_analyst +) + +# Create and run the crew +crew = Crew( + agents=[space_analyst], + tasks=[analysis_task], + verbose=True, + process=Process.sequential +) + +# Example usage +result = crew.kickoff( + inputs={"user_question": "What are the latest developments in space exploration?"} +) +``` + +```output Output +# Agent: Space News Analyst +## Task: Answer this question about space news: What are the latest developments in space exploration? + + +# Agent: Space News Analyst +## Final Answer: +The latest developments in space exploration, based on recent space news articles, include the following: + +1. SpaceX has received the final regulatory approvals to proceed with the second integrated Starship/Super Heavy launch, scheduled for as soon as the morning of Nov. 17, 2023. This is a significant step in SpaceX's ambitious plans for space exploration and colonization. [Source: SpaceNews](https://spacenews.com/starship-cleared-for-nov-17-launch/) + +2. SpaceX has also informed the US Federal Communications Commission (FCC) that it plans to begin launching its first next-generation Starlink Gen2 satellites. This represents a major upgrade to the Starlink satellite internet service, which aims to provide high-speed internet access worldwide. [Source: Teslarati](https://www.teslarati.com/spacex-first-starlink-gen2-satellite-launch-2022/) + +3. AI startup Synthetaic has raised $15 million in Series B funding. The company uses artificial intelligence to analyze data from space and air sensors, which could have significant applications in space exploration and satellite technology. [Source: SpaceNews](https://spacenews.com/ai-startup-synthetaic-raises-15-million-in-series-b-funding/) + +4. The Space Force has formally established a unit within the U.S. Indo-Pacific Command, marking a permanent presence in the Indo-Pacific region. This could have significant implications for space security and geopolitics. [Source: SpaceNews](https://spacenews.com/space-force-establishes-permanent-presence-in-indo-pacific-region/) + +5. Slingshot Aerospace, a space tracking and data analytics company, is expanding its network of ground-based optical telescopes to increase coverage of low Earth orbit. This could improve our ability to track and analyze objects in low Earth orbit, including satellites and space debris. [Source: SpaceNews](https://spacenews.com/slingshots-space-tracking-network-to-extend-coverage-of-low-earth-orbit/) + +6. The National Natural Science Foundation of China has outlined a five-year project for researchers to study the assembly of ultra-large spacecraft. This could lead to significant advancements in spacecraft technology and space exploration capabilities. [Source: SpaceNews](https://spacenews.com/china-researching-challenges-of-kilometer-scale-ultra-large-spacecraft/) + +7. The Center for AEroSpace Autonomy Research (CAESAR) at Stanford University is focusing on spacecraft autonomy. The center held a kickoff event on May 22, 2024, to highlight the industry, academia, and government collaboration it seeks to foster. This could lead to significant advancements in autonomous spacecraft technology. [Source: SpaceNews](https://spacenews.com/stanford-center-focuses-on-spacecraft-autonomy/) +``` + + + +## تصحيح الأخطاء واستكشاف المشاكل + +### تصحيح مشاكل المعرفة + +#### التحقق من تهيئة معرفة Agent +```python +from crewai import Agent, Crew, Task +from crewai.knowledge.source.string_knowledge_source import StringKnowledgeSource + +knowledge_source = StringKnowledgeSource(content="Test knowledge") + +agent = Agent( + role="Test Agent", + goal="Test knowledge", + backstory="Testing", + knowledge_sources=[knowledge_source] +) + +crew = Crew(agents=[agent], tasks=[Task(...)]) + +# Before kickoff - knowledge not initialized +print(f"Before kickoff - Agent knowledge: {getattr(agent, 'knowledge', None)}") + +crew.kickoff() + +# After kickoff - knowledge initialized +print(f"After kickoff - Agent knowledge: {agent.knowledge}") +print(f"Agent knowledge collection: {agent.knowledge.storage.collection_name}") +print(f"Number of sources: {len(agent.knowledge.sources)}") +``` + +#### التحقق من مواقع تخزين المعرفة +```python +import os +from crewai.utilities.paths import db_storage_path + +# Check storage structure +storage_path = db_storage_path() +knowledge_path = os.path.join(storage_path, "knowledge") + +if os.path.exists(knowledge_path): + print("Knowledge collections found:") + for collection in os.listdir(knowledge_path): + collection_path = os.path.join(knowledge_path, collection) + if os.path.isdir(collection_path): + print(f" - {collection}/") + # Show collection contents + for item in os.listdir(collection_path): + print(f" └── {item}") +``` + +#### اختبار استرجاع المعرفة +```python +# Test agent knowledge retrieval +if hasattr(agent, 'knowledge') and agent.knowledge: + test_query = ["test query"] + results = agent.knowledge.query(test_query) + print(f"Agent knowledge results: {len(results)} documents found") + + # Test crew knowledge retrieval (if exists) + if hasattr(crew, 'knowledge') and crew.knowledge: + crew_results = crew.query_knowledge(test_query) + print(f"Crew knowledge results: {len(crew_results)} documents found") +``` + +#### فحص مجموعات المعرفة +```python +import chromadb +from crewai.utilities.paths import db_storage_path +import os + +# Connect to CrewAI's knowledge ChromaDB +knowledge_path = os.path.join(db_storage_path(), "knowledge") + +if os.path.exists(knowledge_path): + client = chromadb.PersistentClient(path=knowledge_path) + collections = client.list_collections() + + print("Knowledge Collections:") + for collection in collections: + print(f" - {collection.name}: {collection.count()} documents") + + # Sample a few documents to verify content + if collection.count() > 0: + sample = collection.peek(limit=2) + print(f" Sample content: {sample['documents'][0][:100]}...") +else: + print("No knowledge storage found") +``` + +#### التحقق من معالجة المعرفة +```python +from crewai.knowledge.source.string_knowledge_source import StringKnowledgeSource + +# Create a test knowledge source +test_source = StringKnowledgeSource( + content="Test knowledge content for debugging", + chunk_size=100, # Small chunks for testing + chunk_overlap=20 +) + +# Check chunking behavior +print(f"Original content length: {len(test_source.content)}") +print(f"Chunk size: {test_source.chunk_size}") +print(f"Chunk overlap: {test_source.chunk_overlap}") + +# Process and inspect chunks +test_source.add() +print(f"Number of chunks created: {len(test_source.chunks)}") +for i, chunk in enumerate(test_source.chunks[:3]): # Show first 3 chunks + print(f"Chunk {i+1}: {chunk[:50]}...") +``` + +### مشاكل تخزين المعرفة الشائعة + +**أخطاء "الملف غير موجود":** +```python +# Ensure files are in the correct location +from crewai.utilities.constants import KNOWLEDGE_DIRECTORY +import os + +knowledge_dir = KNOWLEDGE_DIRECTORY # Usually "knowledge" +file_path = os.path.join(knowledge_dir, "your_file.pdf") + +if not os.path.exists(file_path): + print(f"File not found: {file_path}") + print(f"Current working directory: {os.getcwd()}") + print(f"Expected knowledge directory: {os.path.abspath(knowledge_dir)}") +``` + +**أخطاء "عدم تطابق أبعاد التضمين":** +```python +# This happens when switching embedding providers +# Reset knowledge storage to clear old embeddings +crew.reset_memories(command_type='knowledge') + +# Or use consistent embedding providers +crew = Crew( + agents=[...], + tasks=[...], + knowledge_sources=[...], + embedder={"provider": "openai", "config": {"model": "text-embedding-3-small"}} +) +``` + +**أخطاء "رفض إذن ChromaDB":** +```bash +# Fix storage permissions +chmod -R 755 ~/.local/share/CrewAI/ +``` + +**المعرفة لا تستمر بين عمليات التشغيل:** +```python +# Verify storage location consistency +import os +from crewai.utilities.paths import db_storage_path + +print("CREWAI_STORAGE_DIR:", os.getenv("CREWAI_STORAGE_DIR")) +print("Computed storage path:", db_storage_path()) +print("Knowledge path:", os.path.join(db_storage_path(), "knowledge")) +``` + +### أوامر إعادة تعيين المعرفة + +```python +# Reset only agent-specific knowledge +crew.reset_memories(command_type='agent_knowledge') + +# Reset both crew and agent knowledge +crew.reset_memories(command_type='knowledge') + +# CLI commands +# crewai reset-memories --agent-knowledge # Agent knowledge only +# crewai reset-memories --knowledge # All knowledge +``` + +### مسح المعرفة + +إذا كنت بحاجة إلى مسح المعرفة المخزّنة في CrewAI، يمكنك استخدام أمر `crewai reset-memories` مع خيار `--knowledge`. + +```bash Command +crewai reset-memories --knowledge +``` + +هذا مفيد عندما تكون قد حدّثت مصادر المعرفة وتريد التأكد من أن الوكلاء يستخدمون أحدث المعلومات. + +## أفضل الممارسات + + + + - حافظ على أحجام القطع مناسبة لنوع المحتوى + - ضع في اعتبارك تداخل المحتوى للحفاظ على السياق + - نظّم المعلومات ذات الصلة في مصادر معرفة منفصلة + + + + - اضبط أحجام القطع بناءً على تعقيد المحتوى + - أعدّ نماذج تضمين مناسبة + - ضع في اعتبارك استخدام مزودي تضمين محليين لمعالجة أسرع + + + + - مع هيكل الملفات النموذجي الذي يوفره CrewAI، يتم تضمين مصادر المعرفة في كل مرة يتم فيها تشغيل kickoff. + - إذا كانت مصادر المعرفة كبيرة، فإن هذا يؤدي إلى عدم كفاءة وزيادة وقت الاستجابة، حيث يتم تضمين نفس البيانات في كل مرة. + - لحل هذه المشكلة، قم بتهيئة معامل knowledge مباشرة بدلاً من معامل knowledge_sources. + - رابط للمشكلة للحصول على فكرة كاملة [Github Issue](https://github.com/crewAIInc/crewAI/issues/2755) + + + + - استخدم المعرفة على مستوى Agent للمعلومات الخاصة بالدور + - استخدم المعرفة على مستوى Crew للمعلومات المشتركة التي يحتاجها جميع الوكلاء + - عيّن المُضمّنات على مستوى Agent إذا كنت بحاجة إلى استراتيجيات تضمين مختلفة + - استخدم تسمية مجموعات متسقة بالحفاظ على أدوار Agent وصفية + - اختبر تهيئة المعرفة بالتحقق من agent.knowledge بعد kickoff + - راقب مواقع التخزين لفهم أين يتم تخزين المعرفة + - أعد تعيين المعرفة بشكل مناسب باستخدام أنواع الأوامر الصحيحة + + + + - عيّن `CREWAI_STORAGE_DIR` إلى موقع معروف في الإنتاج + - اختر مزودي تضمين صريحين ليتوافقوا مع إعداد LLM وتجنب تعارضات مفاتيح API + - راقب حجم تخزين المعرفة مع نموه مع إضافات المستندات + - نظّم مصادر المعرفة حسب المجال أو الغرض باستخدام أسماء المجموعات + - ضمّن مجلدات المعرفة في استراتيجيات النسخ الاحتياطي والنشر + - عيّن أذونات ملفات مناسبة لملفات المعرفة ومجلدات التخزين + - استخدم متغيرات البيئة لمفاتيح API والإعدادات الحساسة + + diff --git a/docs/ar/concepts/llms.mdx b/docs/ar/concepts/llms.mdx new file mode 100644 index 000000000..0070b6b9f --- /dev/null +++ b/docs/ar/concepts/llms.mdx @@ -0,0 +1,1464 @@ +--- +title: 'نماذج اللغة الكبيرة (LLMs)' +description: 'دليل شامل لإعداد واستخدام نماذج اللغة الكبيرة (LLMs) في مشاريع CrewAI' +icon: 'microchip-ai' +mode: "wide" +--- + +## نظرة عامة + +يتكامل CrewAI مع مزودي LLM متعددين من خلال حزم SDK الأصلية للمزودين، مما يمنحك المرونة لاختيار النموذج المناسب لحالة الاستخدام الخاصة بك. سيساعدك هذا الدليل على فهم كيفية إعداد واستخدام مزودي LLM المختلفين في مشاريع CrewAI. + + +## ما هي نماذج اللغة الكبيرة؟ + +نماذج اللغة الكبيرة (LLMs) هي الذكاء الأساسي وراء وكلاء CrewAI. تمكّن الوكلاء من فهم السياق واتخاذ القرارات وتوليد استجابات شبيهة بالبشر. إليك ما تحتاج معرفته: + + + + نماذج اللغة الكبيرة هي أنظمة ذكاء اصطناعي مدربة على كميات هائلة من البيانات النصية. تدعم ذكاء وكلاء CrewAI، مما يمكّنهم من فهم وتوليد نصوص شبيهة بالبشر. + + + تحدد نافذة السياق مقدار النص الذي يمكن لـ LLM معالجته في وقت واحد. النوافذ الأكبر (مثل 128K رمز) تتيح سياقًا أكثر لكنها قد تكون أكثر تكلفة وأبطأ. + + + تتحكم درجة الحرارة (0.0 إلى 1.0) في عشوائية الاستجابة. القيم المنخفضة (مثل 0.2) تنتج مخرجات أكثر تركيزًا وحتمية، بينما القيم الأعلى (مثل 0.8) تزيد الإبداع والتنوع. + + + يقدم كل مزود LLM (مثل OpenAI و Anthropic و Google) نماذج مختلفة بقدرات وأسعار وميزات متفاوتة. اختر بناءً على احتياجاتك من الدقة والسرعة والتكلفة. + + + +## إعداد LLM الخاص بك + +هناك أماكن مختلفة في كود CrewAI حيث يمكنك تحديد النموذج المُستخدم. بمجرد تحديد النموذج، ستحتاج إلى توفير الإعداد (مثل مفتاح API) لكل مزود نموذج تستخدمه. انظر قسم [أمثلة إعداد المزودين](#أمثلة-إعداد-المزودين) لمزودك. + + + + أبسط طريقة للبدء. عيّن النموذج في بيئتك مباشرة، من خلال ملف `.env` أو في كود تطبيقك. إذا استخدمت `crewai create` لبدء مشروعك، سيكون مُعيّنًا بالفعل. + + ```bash .env + MODEL=model-id # e.g. gpt-4o, gemini-2.0-flash, claude-3-sonnet-... + + # Be sure to set your API keys here too. See the Provider + # section below. + ``` + + + لا تقم أبدًا بتأكيد مفاتيح API في التحكم بالإصدارات. استخدم ملفات البيئة (.env) أو إدارة أسرار نظامك. + + + + أنشئ ملف YAML لتعريف إعدادات الوكلاء. هذه الطريقة رائعة للتحكم بالإصدارات والتعاون بين الفريق: + + ```yaml agents.yaml {6} + researcher: + role: Research Specialist + goal: Conduct comprehensive research and analysis + backstory: A dedicated research professional with years of experience + verbose: true + llm: provider/model-id # e.g. openai/gpt-4o, google/gemini-2.0-flash, anthropic/claude... + # (see provider configuration examples below for more) + ``` + + + يتيح لك إعداد YAML: + - التحكم بإصدارات إعدادات الوكلاء + - التبديل بسهولة بين النماذج المختلفة + - مشاركة الإعدادات بين أعضاء الفريق + - توثيق خيارات النماذج وأغراضها + + + + لأقصى مرونة، أعدّ LLMs مباشرة في كود Python: + + ```python {4,8} + from crewai import LLM + + # Basic configuration + llm = LLM(model="model-id-here") # gpt-4o, gemini-2.0-flash, anthropic/claude... + + # Advanced configuration with detailed parameters + llm = LLM( + model="model-id-here", # gpt-4o, gemini-2.0-flash, anthropic/claude... + temperature=0.7, # Higher for more creative outputs + timeout=120, # Seconds to wait for response + max_tokens=4000, # Maximum length of response + top_p=0.9, # Nucleus sampling parameter + frequency_penalty=0.1 , # Reduce repetition + presence_penalty=0.1, # Encourage topic diversity + response_format={"type": "json"}, # For structured outputs + seed=42 # For reproducible results + ) + ``` + + + شرح المعاملات: + - `temperature`: تتحكم في العشوائية (0.0-1.0) + - `timeout`: أقصى وقت انتظار للاستجابة + - `max_tokens`: تحدد طول الاستجابة + - `top_p`: بديل لدرجة الحرارة للعينات + - `frequency_penalty`: تقلل تكرار الكلمات + - `presence_penalty`: تشجع موضوعات جديدة + - `response_format`: تحدد هيكل المخرجات + - `seed`: تضمن مخرجات متسقة + + + + + + يوفر CrewAI تكاملات SDK أصلية لـ OpenAI و Anthropic و Google (Gemini API) و Azure و AWS Bedrock -- لا حاجة لتثبيت إضافي بخلاف الملحقات الخاصة بالمزود (مثل `uv add "crewai[openai]"`). + + جميع المزودين الآخرين مدعومون بواسطة **LiteLLM**. إذا كنت تخطط لاستخدام أي منهم، أضفه كتبعية لمشروعك: + ```bash + uv add 'crewai[litellm]' + ``` + + +## أمثلة إعداد المزودين + +يدعم CrewAI العديد من مزودي LLM، كل منهم يقدم ميزات فريدة وطرق مصادقة وقدرات نماذج. +في هذا القسم، ستجد أمثلة مفصلة تساعدك في اختيار وإعداد وتحسين LLM الأنسب لاحتياجات مشروعك. + + + + يوفر CrewAI تكاملًا أصليًا مع OpenAI من خلال OpenAI Python SDK. + + ```toml Code + # Required + OPENAI_API_KEY=sk-... + + # Optional + OPENAI_BASE_URL= + ``` + + **الاستخدام الأساسي:** + ```python Code + from crewai import LLM + + llm = LLM( + model="openai/gpt-4o", + api_key="your-api-key", # Or set OPENAI_API_KEY + temperature=0.7, + max_tokens=4000 + ) + ``` + + **الإعداد المتقدم:** + ```python Code + from crewai import LLM + + llm = LLM( + model="openai/gpt-4o", + api_key="your-api-key", + base_url="https://api.openai.com/v1", # Optional custom endpoint + organization="org-...", # Optional organization ID + project="proj_...", # Optional project ID + temperature=0.7, + max_tokens=4000, + max_completion_tokens=4000, # For newer models + top_p=0.9, + frequency_penalty=0.1, + presence_penalty=0.1, + stop=["END"], + seed=42, # For reproducible outputs + stream=True, # Enable streaming + timeout=60.0, # Request timeout in seconds + max_retries=3, # Maximum retry attempts + logprobs=True, # Return log probabilities + top_logprobs=5, # Number of most likely tokens + reasoning_effort="medium" # For o1 models: low, medium, high + ) + ``` + + **المخرجات المهيكلة:** + ```python Code + from pydantic import BaseModel + from crewai import LLM + + class ResponseFormat(BaseModel): + name: str + age: int + summary: str + + llm = LLM( + model="openai/gpt-4o", + ) + ``` + + **متغيرات البيئة المدعومة:** + - `OPENAI_API_KEY`: مفتاح OpenAI API (مطلوب) + - `OPENAI_BASE_URL`: عنوان URL مخصص لـ OpenAI API (اختياري) + + **الميزات:** + - دعم استدعاء الدوال الأصلي (باستثناء نماذج o1) + - مخرجات منظمة مع JSON schema + - دعم البث للاستجابات في الوقت الفعلي + - تتبع استخدام الرموز + - دعم تسلسلات التوقف (باستثناء نماذج o1) + - احتمالات السجل لرؤى على مستوى الرموز + - التحكم في جهد الاستدلال لنماذج o1 + + **النماذج المدعومة:** + + | النموذج | نافذة السياق | الأفضل لـ | + |---------------------|------------------|-----------------------------------------------| + | gpt-4.1 | 1M tokens | أحدث نموذج بقدرات محسّنة | + | gpt-4.1-mini | 1M tokens | إصدار فعال بسياق كبير | + | gpt-4.1-nano | 1M tokens | متغير فائق الكفاءة | + | gpt-4o | 128,000 tokens | محسّن للسرعة والذكاء | + | gpt-4o-mini | 200,000 tokens | فعال من حيث التكلفة بسياق كبير | + | gpt-4-turbo | 128,000 tokens | المحتوى الطويل، تحليل المستندات | + | gpt-4 | 8,192 tokens | مهام الدقة العالية، الاستدلال المعقد | + | o1 | 200,000 tokens | الاستدلال المتقدم، حل المشكلات المعقدة | + | o1-preview | 128,000 tokens | معاينة قدرات الاستدلال | + | o1-mini | 128,000 tokens | نموذج استدلال فعال | + | o3-mini | 200,000 tokens | نموذج استدلال خفيف | + | o4-mini | 200,000 tokens | استدلال فعال من الجيل التالي | + + **Responses API:** + + تقدم OpenAI واجهتي API: Chat Completions (الافتراضية) و Responses API الأحدث. تم تصميم Responses API من الأساس مع دعم أصلي متعدد الوسائط -- النص والصور والصوت واستدعاءات الدوال كلها مكوّنات أساسية. توفر أداءً أفضل مع نماذج الاستدلال وتدعم ميزات إضافية مثل السلسلة التلقائية والأدوات المدمجة. + + ```python Code + from crewai import LLM + + # Use the Responses API instead of Chat Completions + llm = LLM( + model="openai/gpt-4o", + api="responses", # Enable Responses API + store=True, # Store responses for multi-turn (optional) + auto_chain=True, # Auto-chain for reasoning models (optional) + ) + ``` + + **معاملات Responses API:** + - `api`: عيّن إلى `"responses"` لاستخدام Responses API (الافتراضي: `"completions"`) + - `instructions`: تعليمات على مستوى النظام (Responses API فقط) + - `store`: ما إذا كان يجب تخزين الاستجابات للمحادثات متعددة الأدوار + - `previous_response_id`: معرّف الاستجابة السابقة للمحادثات متعددة الأدوار + - `include`: بيانات إضافية لتضمينها في الاستجابة (مثل `["reasoning.encrypted_content"]`) + - `builtin_tools`: قائمة أدوات OpenAI المدمجة: `"web_search"`, `"file_search"`, `"code_interpreter"`, `"computer_use"` + - `parse_tool_outputs`: إعادة `ResponsesAPIResult` منظمة مع مخرجات أدوات مدمجة محللة + - `auto_chain`: تتبع واستخدام معرّفات الاستجابة تلقائيًا للمحادثات متعددة الأدوار + - `auto_chain_reasoning`: تتبع عناصر الاستدلال المشفرة للامتثال لـ ZDR + + + استخدم Responses API للمشاريع الجديدة، خاصة عند العمل مع نماذج الاستدلال (o1, o3, o4) أو عندما تحتاج دعمًا أصليًا متعدد الوسائط لـ [الملفات](/ar/concepts/files). + + + **ملاحظة:** لاستخدام OpenAI، ثبّت التبعيات المطلوبة: + ```bash + uv add "crewai[openai]" + ``` + + + + توفر Meta Llama API الوصول إلى عائلة نماذج اللغة الكبيرة من Meta. + الـ API متاحة عبر [Meta Llama API](https://llama.developer.meta.com?utm_source=partner-crewai&utm_medium=website). + عيّن متغيرات البيئة التالية في ملف `.env`: + + ```toml Code + # Meta Llama API Key Configuration + LLAMA_API_KEY=LLM|your_api_key_here + ``` + + مثال الاستخدام في مشروع CrewAI: + ```python Code + from crewai import LLM + + # Initialize Meta Llama LLM + llm = LLM( + model="meta_llama/Llama-4-Scout-17B-16E-Instruct-FP8", + temperature=0.8, + stop=["END"], + seed=42 + ) + ``` + + جميع النماذج المدرجة هنا https://llama.developer.meta.com/docs/models/ مدعومة. + + | معرّف النموذج | طول سياق الإدخال | طول سياق المخرجات | وسائط الإدخال | وسائط المخرجات | + | --- | --- | --- | --- | --- | + | `meta_llama/Llama-4-Scout-17B-16E-Instruct-FP8` | 128k | 4028 | نص، صورة | نص | + | `meta_llama/Llama-4-Maverick-17B-128E-Instruct-FP8` | 128k | 4028 | نص، صورة | نص | + | `meta_llama/Llama-3.3-70B-Instruct` | 128k | 4028 | نص | نص | + | `meta_llama/Llama-3.3-8B-Instruct` | 128k | 4028 | نص | نص | + + **ملاحظة:** يستخدم هذا المزود LiteLLM. أضفه كتبعية لمشروعك: + ```bash + uv add 'crewai[litellm]' + ``` + + + + يوفر CrewAI تكاملًا أصليًا مع Anthropic من خلال Anthropic Python SDK. + + ```toml Code + # Required + ANTHROPIC_API_KEY=sk-ant-... + ``` + + **الاستخدام الأساسي:** + ```python Code + from crewai import LLM + + llm = LLM( + model="anthropic/claude-3-5-sonnet-20241022", + api_key="your-api-key", # Or set ANTHROPIC_API_KEY + max_tokens=4096 # Required for Anthropic + ) + ``` + + **الإعداد المتقدم:** + ```python Code + from crewai import LLM + + llm = LLM( + model="anthropic/claude-3-5-sonnet-20241022", + api_key="your-api-key", + base_url="https://api.anthropic.com", # Optional custom endpoint + temperature=0.7, + max_tokens=4096, # Required parameter + top_p=0.9, + stop_sequences=["END", "STOP"], # Anthropic uses stop_sequences + stream=True, # Enable streaming + timeout=60.0, # Request timeout in seconds + max_retries=3 # Maximum retry attempts + ) + ``` + + **التفكير الموسّع (Claude Sonnet 4 وما بعده):** + + يدعم CrewAI ميزة التفكير الموسّع من Anthropic، التي تتيح لـ Claude التفكير في المشكلات بطريقة أكثر شبهًا بالبشر قبل الاستجابة. مفيد بشكل خاص لمهام الاستدلال والتحليل وحل المشكلات المعقدة. + + ```python Code + from crewai import LLM + + # Enable extended thinking with default settings + llm = LLM( + model="anthropic/claude-sonnet-4", + thinking={"type": "enabled"}, + max_tokens=10000 + ) + + # Configure thinking with budget control + llm = LLM( + model="anthropic/claude-sonnet-4", + thinking={ + "type": "enabled", + "budget_tokens": 5000 # Limit thinking tokens + }, + max_tokens=10000 + ) + ``` + + **خيارات إعداد التفكير:** + - `type`: عيّن إلى `"enabled"` لتفعيل وضع التفكير الموسّع + - `budget_tokens` (اختياري): أقصى رموز للتفكير (يساعد في التحكم بالتكاليف) + + **النماذج التي تدعم التفكير الموسّع:** + - `claude-sonnet-4` والنماذج الأحدث + - `claude-3-7-sonnet` (مع قدرات التفكير الموسّع) + + **متى تستخدم التفكير الموسّع:** + - الاستدلال المعقد وحل المشكلات متعددة الخطوات + - الحسابات الرياضية والبراهين + - تحليل الكود وتصحيح الأخطاء + - التخطيط الاستراتيجي واتخاذ القرارات + - البحث والمهام التحليلية + + **ملاحظة:** يستهلك التفكير الموسّع رموزًا إضافية لكنه يمكن أن يحسّن جودة الاستجابة بشكل كبير للمهام المعقدة. + + **متغيرات البيئة المدعومة:** + - `ANTHROPIC_API_KEY`: مفتاح Anthropic API (مطلوب) + + **الميزات:** + - دعم استخدام الأدوات الأصلي لنماذج Claude 3+ + - دعم التفكير الموسّع لـ Claude Sonnet 4+ + - دعم البث للاستجابات في الوقت الفعلي + - معالجة تلقائية لرسائل النظام + - تسلسلات التوقف للتحكم في المخرجات + - تتبع استخدام الرموز + - محادثات استخدام أدوات متعددة الأدوار + + **ملاحظات مهمة:** + - `max_tokens` معامل **مطلوب** لجميع نماذج Anthropic + - يستخدم Claude `stop_sequences` بدلاً من `stop` + - يتم التعامل مع رسائل النظام بشكل منفصل عن رسائل المحادثة + - يجب أن تكون الرسالة الأولى من المستخدم (يتم التعامل معها تلقائيًا) + - يجب أن تتناوب الرسائل بين المستخدم والمساعد + + **النماذج المدعومة:** + + | النموذج | نافذة السياق | الأفضل لـ | + |------------------------------|------------------|-----------------------------------------------| + | claude-sonnet-4 | 200,000 tokens | الأحدث مع قدرات التفكير الموسّع | + | claude-3-7-sonnet | 200,000 tokens | الاستدلال المتقدم والمهام الوكيلية | + | claude-3-5-sonnet-20241022 | 200,000 tokens | أحدث Sonnet بأفضل أداء | + | claude-3-5-haiku | 200,000 tokens | نموذج سريع وصغير للاستجابات السريعة | + | claude-3-opus | 200,000 tokens | الأكثر قدرة للمهام المعقدة | + | claude-3-sonnet | 200,000 tokens | توازن بين الذكاء والسرعة | + | claude-3-haiku | 200,000 tokens | الأسرع للمهام البسيطة | + | claude-2.1 | 200,000 tokens | سياق موسّع، هلوسات أقل | + | claude-2 | 100,000 tokens | نموذج متعدد الاستخدامات | + | claude-instant | 100,000 tokens | سريع وفعال من حيث التكلفة للمهام اليومية | + + **ملاحظة:** لاستخدام Anthropic، ثبّت التبعيات المطلوبة: + ```bash + uv add "crewai[anthropic]" + ``` + + + + يوفر CrewAI تكاملًا أصليًا مع Google Gemini من خلال Google Gen AI Python SDK. + + عيّن مفتاح API في ملف `.env`. إذا كنت بحاجة إلى مفتاح، تحقق من [AI Studio](https://aistudio.google.com/apikey). + + ```toml .env + # Required (one of the following) + GOOGLE_API_KEY= + GEMINI_API_KEY= + + # For Vertex AI Express mode (API key authentication) + GOOGLE_GENAI_USE_VERTEXAI=true + GOOGLE_API_KEY= + + # For Vertex AI with service account + GOOGLE_CLOUD_PROJECT= + GOOGLE_CLOUD_LOCATION= # Defaults to us-central1 + ``` + + **الاستخدام الأساسي:** + ```python Code + from crewai import LLM + + llm = LLM( + model="gemini/gemini-2.0-flash", + api_key="your-api-key", # Or set GOOGLE_API_KEY/GEMINI_API_KEY + temperature=0.7 + ) + ``` + + **الإعداد المتقدم:** + ```python Code + from crewai import LLM + + llm = LLM( + model="gemini/gemini-2.5-flash", + api_key="your-api-key", + temperature=0.7, + top_p=0.9, + top_k=40, # Top-k sampling parameter + max_output_tokens=8192, + stop_sequences=["END", "STOP"], + stream=True, # Enable streaming + safety_settings={ + "HARM_CATEGORY_HARASSMENT": "BLOCK_NONE", + "HARM_CATEGORY_HATE_SPEECH": "BLOCK_NONE" + } + ) + ``` + + **وضع Vertex AI Express (مصادقة بمفتاح API):** + + يتيح لك وضع Vertex AI Express استخدام Vertex AI مع مصادقة بسيطة بمفتاح API بدلاً من بيانات اعتماد حساب الخدمة. هذه أسرع طريقة للبدء مع Vertex AI. + + لتفعيل وضع Express، عيّن متغيري البيئة في ملف `.env`: + ```toml .env + GOOGLE_GENAI_USE_VERTEXAI=true + GOOGLE_API_KEY= + ``` + + ثم استخدم LLM كالمعتاد: + ```python Code + from crewai import LLM + + llm = LLM( + model="gemini/gemini-2.0-flash", + temperature=0.7 + ) + ``` + + + للحصول على مفتاح API لوضع Express: + - مستخدمو Google Cloud الجدد: احصل على [مفتاح API لوضع Express](https://cloud.google.com/vertex-ai/generative-ai/docs/start/quickstart?usertype=apikey) + - مستخدمو Google Cloud الحاليون: احصل على [مفتاح Google Cloud API مرتبط بحساب خدمة](https://cloud.google.com/docs/authentication/api-keys) + + لمزيد من التفاصيل، انظر [وثائق وضع Vertex AI Express](https://docs.cloud.google.com/vertex-ai/generative-ai/docs/start/quickstart?usertype=apikey). + + + **إعداد Vertex AI (حساب خدمة):** + ```python Code + from crewai import LLM + + llm = LLM( + model="gemini/gemini-1.5-pro", + project="your-gcp-project-id", + location="us-central1" # GCP region + ) + ``` + + **متغيرات البيئة المدعومة:** + - `GOOGLE_API_KEY` أو `GEMINI_API_KEY`: مفتاح Google API (مطلوب لـ Gemini API ووضع Vertex AI Express) + - `GOOGLE_GENAI_USE_VERTEXAI`: عيّن إلى `true` لاستخدام Vertex AI (مطلوب لوضع Express) + - `GOOGLE_CLOUD_PROJECT`: معرّف مشروع Google Cloud (لـ Vertex AI مع حساب خدمة) + - `GOOGLE_CLOUD_LOCATION`: موقع GCP (الافتراضي `us-central1`) + + **الميزات:** + - دعم استدعاء الدوال الأصلي لنماذج Gemini 1.5+ و 2.x + - دعم البث للاستجابات في الوقت الفعلي + - قدرات متعددة الوسائط (نص، صور، فيديو) + - إعداد إعدادات الأمان + - دعم لكل من Gemini API و Vertex AI + - معالجة تلقائية لتعليمات النظام + - تتبع استخدام الرموز + + **نماذج Gemini:** + + | النموذج | نافذة السياق | الأفضل لـ | + |--------------------------------|-----------------|-------------------------------------------------------------------| + | gemini-2.5-flash | 1M tokens | التفكير التكيفي، كفاءة التكلفة | + | gemini-2.5-pro | 1M tokens | التفكير والاستدلال المحسّن، الفهم متعدد الوسائط | + | gemini-2.0-flash | 1M tokens | ميزات الجيل التالي، السرعة، التفكير | + | gemini-2.0-flash-thinking | 32,768 tokens | الاستدلال المتقدم مع عملية التفكير | + | gemini-2.0-flash-lite | 1M tokens | كفاءة التكلفة ووقت الاستجابة المنخفض | + | gemini-1.5-pro | 2M tokens | الأفضل أداءً، الاستدلال المنطقي، البرمجة | + | gemini-1.5-flash | 1M tokens | نموذج متعدد الوسائط متوازن، جيد لمعظم المهام | + | gemini-1.5-flash-8b | 1M tokens | الأسرع والأكثر كفاءة من حيث التكلفة | + | gemini-1.0-pro | 32,768 tokens | نموذج الجيل السابق | + + **ملاحظة:** لاستخدام Google Gemini، ثبّت التبعيات المطلوبة: + ```bash + uv add "crewai[google-genai]" + ``` + + القائمة الكاملة للنماذج متاحة في [وثائق نماذج Gemini](https://ai.google.dev/gemini-api/docs/models). + + + + احصل على بيانات الاعتماد من Google Cloud Console واحفظها في ملف JSON، ثم حمّلها بالكود التالي: + ```python Code + import json + + file_path = 'path/to/vertex_ai_service_account.json' + + # Load the JSON file + with open(file_path, 'r') as file: + vertex_credentials = json.load(file) + + # Convert the credentials to a JSON string + vertex_credentials_json = json.dumps(vertex_credentials) + ``` + + مثال الاستخدام في مشروع CrewAI: + ```python Code + from crewai import LLM + + llm = LLM( + model="gemini-1.5-pro-latest", # or vertex_ai/gemini-1.5-pro-latest + temperature=0.7, + vertex_credentials=vertex_credentials_json + ) + ``` + + **ملاحظة:** يستخدم هذا المزود LiteLLM. أضفه كتبعية لمشروعك: + ```bash + uv add 'crewai[litellm]' + ``` + + + + يوفر CrewAI تكاملًا أصليًا مع Azure AI Inference و Azure OpenAI من خلال Azure AI Inference Python SDK. + + ```toml Code + # Required + AZURE_API_KEY= + AZURE_ENDPOINT= + + # Optional + AZURE_API_VERSION= # Defaults to 2024-06-01 + ``` + + **الاستخدام الأساسي:** + ```python Code + llm = LLM( + model="azure/gpt-4", + api_key="", # Or set AZURE_API_KEY + endpoint="", + api_version="2024-06-01" + ) + ``` + + **ملاحظة:** لاستخدام Azure AI Inference، ثبّت التبعيات المطلوبة: + ```bash + uv add "crewai[azure-ai-inference]" + ``` + + + + يوفر CrewAI تكاملًا أصليًا مع AWS Bedrock من خلال boto3 SDK باستخدام Converse API. + + ```toml Code + # Required + AWS_ACCESS_KEY_ID= + AWS_SECRET_ACCESS_KEY= + + # Optional + AWS_SESSION_TOKEN= # For temporary credentials + AWS_DEFAULT_REGION= # Defaults to us-east-1 + AWS_REGION_NAME= # Alternative configuration for backwards compatibility with LiteLLM. Defaults to us-east-1 + ``` + + **الاستخدام الأساسي:** + ```python Code + from crewai import LLM + + llm = LLM( + model="bedrock/anthropic.claude-3-5-sonnet-20241022-v2:0", + region_name="us-east-1" + ) + ``` + + **الإعداد المتقدم:** + ```python Code + from crewai import LLM + + llm = LLM( + model="bedrock/anthropic.claude-3-5-sonnet-20241022-v2:0", + aws_access_key_id="your-access-key", # Or set AWS_ACCESS_KEY_ID + aws_secret_access_key="your-secret-key", # Or set AWS_SECRET_ACCESS_KEY + aws_session_token="your-session-token", # For temporary credentials + region_name="us-east-1", + temperature=0.7, + max_tokens=4096, + top_p=0.9, + top_k=250, # For Claude models + stop_sequences=["END", "STOP"], + stream=True, # Enable streaming + guardrail_config={ # Optional content filtering + "guardrailIdentifier": "your-guardrail-id", + "guardrailVersion": "1" + }, + additional_model_request_fields={ # Model-specific parameters + "top_k": 250 + } + ) + ``` + + **متغيرات البيئة المدعومة:** + - `AWS_ACCESS_KEY_ID`: مفتاح وصول AWS (مطلوب) + - `AWS_SECRET_ACCESS_KEY`: مفتاح AWS السري (مطلوب) + - `AWS_SESSION_TOKEN`: رمز جلسة AWS لبيانات الاعتماد المؤقتة (اختياري) + - `AWS_DEFAULT_REGION`: منطقة AWS (الافتراضي `us-east-1`) + - `AWS_REGION_NAME`: منطقة AWS (الافتراضي `us-east-1`). إعداد بديل للتوافق مع LiteLLM + + **الميزات:** + - دعم استدعاء الأدوات الأصلي عبر Converse API + - استجابات بث وبدون بث + - معالجة أخطاء شاملة مع منطق إعادة المحاولة + - إعداد حواجز الحماية لتصفية المحتوى + - معاملات خاصة بالنموذج عبر `additional_model_request_fields` + - تتبع استخدام الرموز وتسجيل سبب التوقف + - دعم جميع نماذج Bedrock الأساسية + - معالجة تلقائية لتنسيق المحادثة + + **ملاحظات مهمة:** + - يستخدم Converse API الحديث للوصول الموحد للنماذج + - معالجة تلقائية لمتطلبات المحادثة الخاصة بالنموذج + - يتم التعامل مع رسائل النظام بشكل منفصل عن المحادثة + - يجب أن تكون الرسالة الأولى من المستخدم (يتم التعامل معها تلقائيًا) + - بعض النماذج (مثل Cohere) تتطلب أن تنتهي المحادثة برسالة المستخدم + + [Amazon Bedrock](https://docs.aws.amazon.com/bedrock/latest/userguide/models-regions.html) هو خدمة مُدارة توفر الوصول إلى نماذج أساسية متعددة من أبرز شركات الذكاء الاصطناعي عبر واجهة API موحدة. + + | النموذج | نافذة السياق | الأفضل لـ | + |-------------------------|----------------------|-------------------------------------------------------------------| + | Amazon Nova Pro | حتى 300k tokens | أداء عالٍ، نموذج يوازن بين الدقة والسرعة والفعالية من حيث التكلفة عبر مهام متنوعة. | + | Amazon Nova Micro | حتى 128k tokens | نموذج نصي فقط عالي الأداء وفعال من حيث التكلفة ومحسّن لأقل وقت استجابة. | + | Amazon Nova Lite | حتى 300k tokens | معالجة متعددة الوسائط بأسعار معقولة للصور والفيديو والنص مع قدرات في الوقت الفعلي. | + | Claude 3.7 Sonnet | حتى 128k tokens | الأفضل أداءً للاستدلال المعقد والبرمجة ووكلاء الذكاء الاصطناعي | + | Claude 3.5 Sonnet v2 | حتى 200k tokens | نموذج متطور متخصص في هندسة البرمجيات والقدرات الوكيلية والتفاعل مع الحاسوب بتكلفة محسّنة. | + | Claude 3.5 Sonnet | حتى 200k tokens | نموذج عالي الأداء يقدم ذكاءً واستدلالًا فائقين عبر مهام متنوعة مع توازن مثالي بين السرعة والتكلفة. | + | Claude 3.5 Haiku | حتى 200k tokens | نموذج متعدد الوسائط سريع وصغير محسّن للاستجابات السريعة والتفاعلات الشبيهة بالبشر | + | Claude 3 Sonnet | حتى 200k tokens | نموذج متعدد الوسائط يوازن بين الذكاء والسرعة للنشر بكميات كبيرة. | + | Claude 3 Haiku | حتى 200k tokens | نموذج متعدد الوسائط صغير وسريع محسّن للاستجابات السريعة والتفاعلات المحادثية الطبيعية | + | Claude 3 Opus | حتى 200k tokens | أكثر النماذج متعددة الوسائط تقدمًا يتفوق في المهام المعقدة بالاستدلال الشبيه بالبشر والفهم السياقي الفائق. | + | Claude 2.1 | حتى 200k tokens | إصدار محسّن بنافذة سياق موسّعة وموثوقية محسّنة وهلوسات أقل لتطبيقات النصوص الطويلة وRAG | + | Claude | حتى 100k tokens | نموذج متعدد الاستخدامات يتفوق في الحوار المتقدم والمحتوى الإبداعي واتباع التعليمات الدقيقة. | + | Claude Instant | حتى 100k tokens | نموذج سريع وفعال من حيث التكلفة للمهام اليومية مثل الحوار والتحليل والتلخيص والأسئلة والأجوبة | + | Llama 3.1 405B Instruct | حتى 128k tokens | نموذج LLM متقدم لتوليد البيانات الاصطناعية والتقطير والاستدلال لروبوتات المحادثة والبرمجة والمهام المتخصصة. | + | Llama 3.1 70B Instruct | حتى 128k tokens | يدعم المحادثات المعقدة مع فهم سياقي فائق واستدلال وتوليد نص. | + | Llama 3.1 8B Instruct | حتى 128k tokens | نموذج متطور مع فهم اللغة واستدلال فائق وتوليد النص. | + | Llama 3 70B Instruct | حتى 8k tokens | يدعم المحادثات المعقدة مع فهم سياقي فائق واستدلال وتوليد نص. | + | Llama 3 8B Instruct | حتى 8k tokens | نموذج LLM متطور مع فهم اللغة واستدلال فائق وتوليد النص. | + | Titan Text G1 - Lite | حتى 4k tokens | نموذج خفيف وفعال من حيث التكلفة محسّن لمهام اللغة الإنجليزية والضبط الدقيق مع التركيز على التلخيص وتوليد المحتوى. | + | Titan Text G1 - Express | حتى 8k tokens | نموذج متعدد الاستخدامات لمهام اللغة العامة والمحادثة وتطبيقات RAG مع دعم الإنجليزية وأكثر من 100 لغة. | + | Cohere Command | حتى 4k tokens | نموذج متخصص في اتباع أوامر المستخدم وتقديم حلول عملية للمؤسسات. | + | Jurassic-2 Mid | حتى 8,191 tokens | نموذج فعال من حيث التكلفة يوازن بين الجودة والسعر لمهام اللغة المتنوعة مثل الأسئلة والأجوبة والتلخيص وتوليد المحتوى. | + | Jurassic-2 Ultra | حتى 8,191 tokens | نموذج لتوليد النص المتقدم والفهم، يتفوق في المهام المعقدة مثل التحليل وإنشاء المحتوى. | + | Jamba-Instruct | حتى 256k tokens | نموذج بنافذة سياق موسّعة محسّن لتوليد النص الفعال من حيث التكلفة والتلخيص والأسئلة والأجوبة. | + | Mistral 7B Instruct | حتى 32k tokens | نموذج LLM يتبع التعليمات ويكمل الطلبات ويولد نصًا إبداعيًا. | + | Mistral 8x7B Instruct | حتى 32k tokens | نموذج LLM بمعمارية MOE يتبع التعليمات ويكمل الطلبات ويولد نصًا إبداعيًا. | + | DeepSeek R1 | 32,768 tokens | نموذج استدلال متقدم | + + **ملاحظة:** لاستخدام AWS Bedrock، ثبّت التبعيات المطلوبة: + ```bash + uv add "crewai[bedrock]" + ``` + + + + ```toml Code + AWS_ACCESS_KEY_ID= + AWS_SECRET_ACCESS_KEY= + AWS_DEFAULT_REGION= + ``` + + مثال الاستخدام في مشروع CrewAI: + ```python Code + llm = LLM( + model="sagemaker/" + ) + ``` + + **ملاحظة:** يستخدم هذا المزود LiteLLM. أضفه كتبعية لمشروعك: + ```bash + uv add 'crewai[litellm]' + ``` + + + + عيّن متغيرات البيئة التالية في ملف `.env`: + ```toml Code + MISTRAL_API_KEY= + ``` + + مثال الاستخدام في مشروع CrewAI: + ```python Code + llm = LLM( + model="mistral/mistral-large-latest", + temperature=0.7 + ) + ``` + + **ملاحظة:** يستخدم هذا المزود LiteLLM. أضفه كتبعية لمشروعك: + ```bash + uv add 'crewai[litellm]' + ``` + + + + عيّن متغيرات البيئة التالية في ملف `.env`: + ```toml Code + NVIDIA_API_KEY= + ``` + + مثال الاستخدام في مشروع CrewAI: + ```python Code + llm = LLM( + model="nvidia_nim/meta/llama3-70b-instruct", + temperature=0.7 + ) + ``` + + يوفر Nvidia NIM مجموعة شاملة من النماذج لحالات الاستخدام المتنوعة، من المهام ذات الأغراض العامة إلى التطبيقات المتخصصة. + + | النموذج | نافذة السياق | الأفضل لـ | + |-------------------------------------------------------------------------|----------------|-------------------------------------------------------------------| + | nvidia/mistral-nemo-minitron-8b-8k-instruct | 8,192 tokens | نموذج لغة صغير متطور يقدم دقة فائقة لروبوتات المحادثة والمساعدين الافتراضيين وتوليد المحتوى. | + | nvidia/nemotron-4-mini-hindi-4b-instruct | 4,096 tokens | نموذج لغة صغير ثنائي اللغة هندي-إنجليزي للاستدلال على الجهاز، مصمم خصيصًا للغة الهندية. | + | nvidia/llama-3.1-nemotron-70b-instruct | 128k tokens | مخصص لتعزيز فائدة الاستجابات | + | nvidia/llama3-chatqa-1.5-8b | 128k tokens | نموذج LLM متقدم لتوليد استجابات عالية الجودة ومدركة للسياق لروبوتات المحادثة ومحركات البحث. | + | nvidia/llama3-chatqa-1.5-70b | 128k tokens | نموذج LLM متقدم لتوليد استجابات عالية الجودة ومدركة للسياق لروبوتات المحادثة ومحركات البحث. | + | nvidia/vila | 128k tokens | نموذج رؤية-لغة متعدد الوسائط يفهم النص والصور والفيديو وينشئ استجابات غنية بالمعلومات | + | nvidia/neva-22 | 4,096 tokens | نموذج رؤية-لغة متعدد الوسائط يفهم النص والصور ويولد استجابات غنية بالمعلومات | + | nvidia/nemotron-mini-4b-instruct | 8,192 tokens | مهام ذات أغراض عامة | + | nvidia/usdcode-llama3-70b-instruct | 128k tokens | نموذج LLM متطور يجيب على استعلامات معرفة OpenUSD ويولد كود USD-Python. | + | nvidia/nemotron-4-340b-instruct | 4,096 tokens | ينشئ بيانات اصطناعية متنوعة تحاكي خصائص بيانات العالم الحقيقي. | + | meta/codellama-70b | 100k tokens | نموذج LLM قادر على توليد الكود من اللغة الطبيعية والعكس. | + | meta/llama2-70b | 4,096 tokens | نموذج لغة كبير متطور قادر على توليد النص والكود استجابة للمطالبات. | + | meta/llama3-8b-instruct | 8,192 tokens | نموذج LLM متطور مع فهم اللغة واستدلال فائق وتوليد النص. | + | meta/llama3-70b-instruct | 8,192 tokens | يدعم المحادثات المعقدة مع فهم سياقي فائق واستدلال وتوليد نص. | + | meta/llama-3.1-8b-instruct | 128k tokens | نموذج متطور مع فهم اللغة واستدلال فائق وتوليد النص. | + | meta/llama-3.1-70b-instruct | 128k tokens | يدعم المحادثات المعقدة مع فهم سياقي فائق واستدلال وتوليد نص. | + | meta/llama-3.1-405b-instruct | 128k tokens | نموذج LLM متقدم لتوليد البيانات الاصطناعية والتقطير والاستدلال لروبوتات المحادثة والبرمجة والمهام المتخصصة. | + | meta/llama-3.2-1b-instruct | 128k tokens | نموذج لغة صغير متطور مع فهم اللغة واستدلال فائق وتوليد النص. | + | meta/llama-3.2-3b-instruct | 128k tokens | نموذج لغة صغير متطور مع فهم اللغة واستدلال فائق وتوليد النص. | + | meta/llama-3.2-11b-vision-instruct | 128k tokens | نموذج لغة صغير متطور مع فهم اللغة واستدلال فائق وتوليد النص. | + | meta/llama-3.2-90b-vision-instruct | 128k tokens | نموذج لغة صغير متطور مع فهم اللغة واستدلال فائق وتوليد النص. | + | google/gemma-7b | 8,192 tokens | نموذج متطور لتوليد النص وفهمه وتحويله وتوليد الكود. | + | google/gemma-2b | 8,192 tokens | نموذج متطور لتوليد النص وفهمه وتحويله وتوليد الكود. | + | google/codegemma-7b | 8,192 tokens | نموذج متطور مبني على Gemma-7B من Google متخصص في توليد الكود وإكماله. | + | google/codegemma-1.1-7b | 8,192 tokens | نموذج برمجة متقدم لتوليد الكود وإكماله والاستدلال واتباع التعليمات. | + | google/recurrentgemma-2b | 8,192 tokens | نموذج لغة بمعمارية تكرارية جديدة لاستدلال أسرع عند توليد تسلسلات طويلة. | + | google/gemma-2-9b-it | 8,192 tokens | نموذج متطور لتوليد النص وفهمه وتحويله وتوليد الكود. | + | google/gemma-2-27b-it | 8,192 tokens | نموذج متطور لتوليد النص وفهمه وتحويله وتوليد الكود. | + | google/gemma-2-2b-it | 8,192 tokens | نموذج متطور لتوليد النص وفهمه وتحويله وتوليد الكود. | + | google/deplot | 512 tokens | نموذج فهم لغة بصرية بلقطة واحدة يترجم صور الرسوم البيانية إلى جداول. | + | google/paligemma | 8,192 tokens | نموذج لغة بصري بارع في استيعاب مدخلات النص والصور لإنتاج استجابات غنية بالمعلومات. | + | mistralai/mistral-7b-instruct-v0.2 | 32k tokens | نموذج LLM يتبع التعليمات ويكمل الطلبات ويولد نصًا إبداعيًا. | + | mistralai/mixtral-8x7b-instruct-v0.1 | 8,192 tokens | نموذج LLM بمعمارية MOE يتبع التعليمات ويكمل الطلبات ويولد نصًا إبداعيًا. | + | mistralai/mistral-large | 4,096 tokens | ينشئ بيانات اصطناعية متنوعة تحاكي خصائص بيانات العالم الحقيقي. | + | mistralai/mixtral-8x22b-instruct-v0.1 | 8,192 tokens | ينشئ بيانات اصطناعية متنوعة تحاكي خصائص بيانات العالم الحقيقي. | + | mistralai/mistral-7b-instruct-v0.3 | 32k tokens | نموذج LLM يتبع التعليمات ويكمل الطلبات ويولد نصًا إبداعيًا. | + | nv-mistralai/mistral-nemo-12b-instruct | 128k tokens | أكثر نموذج لغة تقدمًا للاستدلال والبرمجة والمهام متعددة اللغات؛ يعمل على وحدة GPU واحدة. | + | mistralai/mamba-codestral-7b-v0.1 | 256k tokens | نموذج للكتابة والتفاعل مع الكود عبر مجموعة واسعة من لغات البرمجة والمهام. | + | microsoft/phi-3-mini-128k-instruct | 128K tokens | نموذج LLM مفتوح خفيف ومتطور مع مهارات قوية في الرياضيات والاستدلال المنطقي. | + | microsoft/phi-3-mini-4k-instruct | 4,096 tokens | نموذج LLM مفتوح خفيف ومتطور مع مهارات قوية في الرياضيات والاستدلال المنطقي. | + | microsoft/phi-3-small-8k-instruct | 8,192 tokens | نموذج LLM مفتوح خفيف ومتطور مع مهارات قوية في الرياضيات والاستدلال المنطقي. | + | microsoft/phi-3-small-128k-instruct | 128K tokens | نموذج LLM مفتوح خفيف ومتطور مع مهارات قوية في الرياضيات والاستدلال المنطقي. | + | microsoft/phi-3-medium-4k-instruct | 4,096 tokens | نموذج LLM مفتوح خفيف ومتطور مع مهارات قوية في الرياضيات والاستدلال المنطقي. | + | microsoft/phi-3-medium-128k-instruct | 128K tokens | نموذج LLM مفتوح خفيف ومتطور مع مهارات قوية في الرياضيات والاستدلال المنطقي. | + | microsoft/phi-3.5-mini-instruct | 128K tokens | نموذج LLM خفيف متعدد اللغات يدعم تطبيقات الذكاء الاصطناعي في البيئات المحدودة بالكمون والذاكرة والحوسبة | + | microsoft/phi-3.5-moe-instruct | 128K tokens | نموذج LLM متقدم يعتمد على معمارية خليط الخبراء لتوليد محتوى فعال حوسبيًا | + | microsoft/kosmos-2 | 1,024 tokens | نموذج متعدد الوسائط رائد مصمم لفهم العناصر المرئية في الصور والاستدلال عليها. | + | microsoft/phi-3-vision-128k-instruct | 128k tokens | نموذج متعدد الوسائط مفتوح متطور يتفوق في الاستدلال عالي الجودة من الصور. | + | microsoft/phi-3.5-vision-instruct | 128k tokens | نموذج متعدد الوسائط مفتوح متطور يتفوق في الاستدلال عالي الجودة من الصور. | + | databricks/dbrx-instruct | 12k tokens | نموذج LLM للأغراض العامة بأداء متطور في فهم اللغة والبرمجة وRAG. | + | snowflake/arctic | 1,024 tokens | يقدم استدلالًا عالي الكفاءة لتطبيقات المؤسسات مع التركيز على توليد SQL والبرمجة. | + | aisingapore/sea-lion-7b-instruct | 4,096 tokens | نموذج LLM لتمثيل وخدمة التنوع اللغوي والثقافي لجنوب شرق آسيا | + | ibm/granite-8b-code-instruct | 4,096 tokens | نموذج LLM لبرمجة البرمجيات لتوليد الكود وإكماله وشرحه والتحويل متعدد الأدوار. | + | ibm/granite-34b-code-instruct | 8,192 tokens | نموذج LLM لبرمجة البرمجيات لتوليد الكود وإكماله وشرحه والتحويل متعدد الأدوار. | + | ibm/granite-3.0-8b-instruct | 4,096 tokens | نموذج لغة صغير متقدم يدعم RAG والتلخيص والتصنيف والكود والذكاء الاصطناعي الوكيلي | + | ibm/granite-3.0-3b-a800m-instruct | 4,096 tokens | نموذج خليط خبراء عالي الكفاءة لـ RAG والتلخيص واستخراج الكيانات والتصنيف | + | mediatek/breeze-7b-instruct | 4,096 tokens | ينشئ بيانات اصطناعية متنوعة تحاكي خصائص بيانات العالم الحقيقي. | + | upstage/solar-10.7b-instruct | 4,096 tokens | يتفوق في مهام NLP، خاصة في اتباع التعليمات والاستدلال والرياضيات. | + | writer/palmyra-med-70b-32k | 32k tokens | نموذج LLM رائد للاستجابات الدقيقة والمناسبة للسياق في المجال الطبي. | + | writer/palmyra-med-70b | 32k tokens | نموذج LLM رائد للاستجابات الدقيقة والمناسبة للسياق في المجال الطبي. | + | writer/palmyra-fin-70b-32k | 32k tokens | نموذج LLM متخصص في التحليل المالي وإعداد التقارير ومعالجة البيانات | + | 01-ai/yi-large | 32k tokens | نموذج قوي مدرب على الإنجليزية والصينية لمهام متنوعة بما في ذلك روبوتات المحادثة والكتابة الإبداعية. | + | deepseek-ai/deepseek-coder-6.7b-instruct | 2k tokens | نموذج برمجة قوي يقدم قدرات متقدمة في توليد الكود وإكماله وملء الفراغات | + | rakuten/rakutenai-7b-instruct | 1,024 tokens | نموذج LLM متطور مع فهم اللغة واستدلال فائق وتوليد النص. | + | rakuten/rakutenai-7b-chat | 1,024 tokens | نموذج LLM متطور مع فهم اللغة واستدلال فائق وتوليد النص. | + | baichuan-inc/baichuan2-13b-chat | 4,096 tokens | يدعم المحادثة بالصينية والإنجليزية والبرمجة والرياضيات واتباع التعليمات وحل الألغاز | + + **ملاحظة:** يستخدم هذا المزود LiteLLM. أضفه كتبعية لمشروعك: + ```bash + uv add 'crewai[litellm]' + ``` + + + + + يتيح لك NVIDIA NIM تشغيل نماذج LLM قوية محليًا على جهاز Windows باستخدام WSL2 (نظام Windows الفرعي لـ Linux). + يتيح لك هذا النهج الاستفادة من وحدة GPU من NVIDIA لاستدلال ذكاء اصطناعي خاص وآمن وفعال من حيث التكلفة دون الاعتماد على الخدمات السحابية. + مثالي لسيناريوهات التطوير والاختبار أو الإنتاج حيث تكون خصوصية البيانات أو القدرات غير المتصلة مطلوبة. + + إليك دليلًا خطوة بخطوة لإعداد نموذج NVIDIA NIM محلي: + + 1. اتبع تعليمات التثبيت من [موقع NVIDIA](https://docs.nvidia.com/nim/wsl2/latest/getting-started.html) + + 2. ثبّت النموذج المحلي. لـ Llama 3.1-8b اتبع [التعليمات](https://build.nvidia.com/meta/llama-3_1-8b-instruct/deploy) + + 3. أعدّ نماذج crewai المحلية: + + ```python Code + from crewai.llm import LLM + + local_nvidia_nim_llm = LLM( + model="openai/meta/llama-3.1-8b-instruct", # it's an openai-api compatible model + base_url="http://localhost:8000/v1", + api_key="", # api_key is required, but you can use any text + ) + + # Then you can use it in your crew: + + @CrewBase + class MyCrew(): + # ... + + @agent + def researcher(self) -> Agent: + return Agent( + config=self.agents_config['researcher'], # type: ignore[index] + llm=local_nvidia_nim_llm + ) + + # ... + ``` + + **ملاحظة:** يستخدم هذا المزود LiteLLM. أضفه كتبعية لمشروعك: + ```bash + uv add 'crewai[litellm]' + ``` + + + + عيّن متغيرات البيئة التالية في ملف `.env`: + + ```toml Code + GROQ_API_KEY= + ``` + + مثال الاستخدام في مشروع CrewAI: + ```python Code + llm = LLM( + model="groq/llama-3.2-90b-text-preview", + temperature=0.7 + ) + ``` + | النموذج | نافذة السياق | الأفضل لـ | + |-------------------|------------------|--------------------------------------------| + | Llama 3.1 70B/8B | 131,072 tokens | مهام عالية الأداء بسياق كبير | + | Llama 3.2 Series | 8,192 tokens | مهام ذات أغراض عامة | + | Mixtral 8x7B | 32,768 tokens | أداء متوازن وسياق جيد | + + **ملاحظة:** يستخدم هذا المزود LiteLLM. أضفه كتبعية لمشروعك: + ```bash + uv add 'crewai[litellm]' + ``` + + + + عيّن متغيرات البيئة التالية في ملف `.env`: + ```toml Code + # Required + WATSONX_URL= + WATSONX_APIKEY= + WATSONX_PROJECT_ID= + + # Optional + WATSONX_TOKEN= + WATSONX_DEPLOYMENT_SPACE_ID= + ``` + + مثال الاستخدام في مشروع CrewAI: + ```python Code + llm = LLM( + model="watsonx/meta-llama/llama-3-1-70b-instruct", + base_url="https://api.watsonx.ai/v1" + ) + ``` + + **ملاحظة:** يستخدم هذا المزود LiteLLM. أضفه كتبعية لمشروعك: + ```bash + uv add 'crewai[litellm]' + ``` + + + + 1. ثبّت Ollama: [ollama.ai](https://ollama.ai/) + 2. شغّل نموذجًا: `ollama run llama3` + 3. أعدّ: + + ```python Code + llm = LLM( + model="ollama/llama3:70b", + base_url="http://localhost:11434" + ) + ``` + + **ملاحظة:** يستخدم هذا المزود LiteLLM. أضفه كتبعية لمشروعك: + ```bash + uv add 'crewai[litellm]' + ``` + + + + عيّن متغيرات البيئة التالية في ملف `.env`: + ```toml Code + FIREWORKS_API_KEY= + ``` + + مثال الاستخدام في مشروع CrewAI: + ```python Code + llm = LLM( + model="fireworks_ai/accounts/fireworks/models/llama-v3-70b-instruct", + temperature=0.7 + ) + ``` + + **ملاحظة:** يستخدم هذا المزود LiteLLM. أضفه كتبعية لمشروعك: + ```bash + uv add 'crewai[litellm]' + ``` + + + + عيّن متغيرات البيئة التالية في ملف `.env`: + ```toml Code + PERPLEXITY_API_KEY= + ``` + + مثال الاستخدام في مشروع CrewAI: + ```python Code + llm = LLM( + model="llama-3.1-sonar-large-128k-online", + base_url="https://api.perplexity.ai/" + ) + ``` + + **ملاحظة:** يستخدم هذا المزود LiteLLM. أضفه كتبعية لمشروعك: + ```bash + uv add 'crewai[litellm]' + ``` + + + + عيّن متغيرات البيئة التالية في ملف `.env`: + ```toml Code + HF_TOKEN= + ``` + + مثال الاستخدام في مشروع CrewAI: + ```python Code + llm = LLM( + model="huggingface/meta-llama/Meta-Llama-3.1-8B-Instruct" + ) + ``` + + **ملاحظة:** يستخدم هذا المزود LiteLLM. أضفه كتبعية لمشروعك: + ```bash + uv add 'crewai[litellm]' + ``` + + + + عيّن متغيرات البيئة التالية في ملف `.env`: + + ```toml Code + SAMBANOVA_API_KEY= + ``` + + مثال الاستخدام في مشروع CrewAI: + ```python Code + llm = LLM( + model="sambanova/Meta-Llama-3.1-8B-Instruct", + temperature=0.7 + ) + ``` + | النموذج | نافذة السياق | الأفضل لـ | + |--------------------|------------------------|----------------------------------------------| + | Llama 3.1 70B/8B | حتى 131,072 tokens | مهام عالية الأداء بسياق كبير | + | Llama 3.1 405B | 8,192 tokens | أداء عالٍ وجودة مخرجات | + | Llama 3.2 Series | 8,192 tokens | مهام عامة ومتعددة الوسائط | + | Llama 3.3 70B | حتى 131,072 tokens | أداء عالٍ وجودة مخرجات | + | Qwen2 familly | 8,192 tokens | أداء عالٍ وجودة مخرجات | + + **ملاحظة:** يستخدم هذا المزود LiteLLM. أضفه كتبعية لمشروعك: + ```bash + uv add 'crewai[litellm]' + ``` + + + + عيّن متغيرات البيئة التالية في ملف `.env`: + ```toml Code + # Required + CEREBRAS_API_KEY= + ``` + + مثال الاستخدام في مشروع CrewAI: + ```python Code + llm = LLM( + model="cerebras/llama3.1-70b", + temperature=0.7, + max_tokens=8192 + ) + ``` + + + ميزات Cerebras: + - سرعات استدلال عالية + - أسعار تنافسية + - توازن جيد بين السرعة والجودة + - دعم نوافذ سياق طويلة + + + **ملاحظة:** يستخدم هذا المزود LiteLLM. أضفه كتبعية لمشروعك: + ```bash + uv add 'crewai[litellm]' + ``` + + + + عيّن متغيرات البيئة التالية في ملف `.env`: + ```toml Code + OPENROUTER_API_KEY= + ``` + + مثال الاستخدام في مشروع CrewAI: + ```python Code + llm = LLM( + model="openrouter/deepseek/deepseek-r1", + base_url="https://openrouter.ai/api/v1", + api_key=OPENROUTER_API_KEY + ) + ``` + + + نماذج Open Router: + - openrouter/deepseek/deepseek-r1 + - openrouter/deepseek/deepseek-chat + + + **ملاحظة:** يستخدم هذا المزود LiteLLM. أضفه كتبعية لمشروعك: + ```bash + uv add 'crewai[litellm]' + ``` + + + + عيّن متغيرات البيئة التالية في ملف `.env`: + ```toml Code + NEBIUS_API_KEY= + ``` + + مثال الاستخدام في مشروع CrewAI: + ```python Code + llm = LLM( + model="nebius/Qwen/Qwen3-30B-A3B" + ) + ``` + + + ميزات Nebius AI Studio: + - مجموعة كبيرة من النماذج مفتوحة المصدر + - حدود معدل أعلى + - أسعار تنافسية + - توازن جيد بين السرعة والجودة + + + **ملاحظة:** يستخدم هذا المزود LiteLLM. أضفه كتبعية لمشروعك: + ```bash + uv add 'crewai[litellm]' + ``` + + + +## بث الاستجابات + +يدعم CrewAI بث الاستجابات من LLMs، مما يتيح لتطبيقك تلقي ومعالجة المخرجات في الوقت الفعلي فور توليدها. + + + + فعّل البث بتعيين معامل `stream` إلى `True` عند تهيئة LLM: + + ```python + from crewai import LLM + + # Create an LLM with streaming enabled + llm = LLM( + model="openai/gpt-4o", + stream=True # Enable streaming + ) + ``` + + عند تفعيل البث، يتم تسليم الاستجابات في أجزاء فور توليدها، مما يخلق تجربة مستخدم أكثر استجابة. + + + + يُصدر CrewAI أحداثًا لكل جزء يتم تلقيه أثناء البث: + + ```python + from crewai.events import ( + LLMStreamChunkEvent + ) + from crewai.events import BaseEventListener + + class MyCustomListener(BaseEventListener): + def setup_listeners(self, crewai_event_bus): + @crewai_event_bus.on(LLMStreamChunkEvent) + def on_llm_stream_chunk(self, event: LLMStreamChunkEvent): + # Process each chunk as it arrives + print(f"Received chunk: {event.chunk}") + + my_listener = MyCustomListener() + ``` + + + [انقر هنا](/ar/concepts/event-listener#event-listeners) لمزيد من التفاصيل + + + + + جميع أحداث LLM في CrewAI تتضمن معلومات Agent والمهمة، مما يتيح لك تتبع وتصفية تفاعلات LLM بواسطة وكلاء أو مهام محددة: + + ```python + from crewai import LLM, Agent, Task, Crew + from crewai.events import LLMStreamChunkEvent + from crewai.events import BaseEventListener + + class MyCustomListener(BaseEventListener): + def setup_listeners(self, crewai_event_bus): + @crewai_event_bus.on(LLMStreamChunkEvent) + def on_llm_stream_chunk(source, event): + if researcher.id == event.agent_id: + print("\n==============\n Got event:", event, "\n==============\n") + + + my_listener = MyCustomListener() + + llm = LLM(model="gpt-4o-mini", temperature=0, stream=True) + + researcher = Agent( + role="About User", + goal="You know everything about the user.", + backstory="""You are a master at understanding people and their preferences.""", + llm=llm, + ) + + search = Task( + description="Answer the following questions about the user: {question}", + expected_output="An answer to the question.", + agent=researcher, + ) + + crew = Crew(agents=[researcher], tasks=[search]) + + result = crew.kickoff( + inputs={"question": "..."} + ) + ``` + + + هذه الميزة مفيدة بشكل خاص لـ: + - تصحيح سلوكيات وكلاء محددة + - تسجيل استخدام LLM حسب نوع المهمة + - مراجعة أي الوكلاء يجرون أنواع استدعاءات LLM + - مراقبة أداء مهام محددة + + + + +## استدعاءات LLM غير المتزامنة + +يدعم CrewAI استدعاءات LLM غير المتزامنة لأداء وتزامن محسّنين في سير عمل الذكاء الاصطناعي. تتيح لك الاستدعاءات غير المتزامنة تشغيل طلبات LLM متعددة بشكل متزامن دون حجب، مما يجعلها مثالية لتطبيقات الإنتاجية العالية وعمليات الوكلاء المتوازية. + + + + استخدم دالة `acall` لطلبات LLM غير المتزامنة: + + ```python + import asyncio + from crewai import LLM + + async def main(): + llm = LLM(model="openai/gpt-4o") + + # Single async call + response = await llm.acall("What is the capital of France?") + print(response) + + asyncio.run(main()) + ``` + + تدعم دالة `acall` جميع المعاملات نفسها كدالة `call` المتزامنة، بما في ذلك الرسائل والأدوات ودوال الاسترجاع. + + + + اجمع بين الاستدعاءات غير المتزامنة والبث للاستجابات المتزامنة في الوقت الفعلي: + + ```python + import asyncio + from crewai import LLM + + async def stream_async(): + llm = LLM(model="openai/gpt-4o", stream=True) + + response = await llm.acall("Write a short story about AI") + + print(response) + + asyncio.run(stream_async()) + ``` + + + +## استدعاءات LLM المهيكلة + +يدعم CrewAI الاستجابات المهيكلة من استدعاءات LLM من خلال السماح لك بتحديد `response_format` باستخدام نموذج Pydantic. يمكّن هذا الإطار من تحليل المخرجات والتحقق منها تلقائيًا، مما يسهّل دمج الاستجابة في تطبيقك دون معالجة لاحقة يدوية. + +```python Code +from crewai import LLM + +class Dog(BaseModel): + name: str + age: int + breed: str + + +llm = LLM(model="gpt-4o", response_format=Dog) + +response = llm.call( + "Analyze the following messages and return the name, age, and breed. " + "Meet Kona! She is 3 years old and is a black german shepherd." +) +print(response) + +# Output: +# Dog(name='Kona', age=3, breed='black german shepherd') +``` + +## الميزات المتقدمة والتحسين + +تعلّم كيفية الاستفادة القصوى من إعداد LLM: + + + + يتضمن CrewAI ميزات إدارة سياق ذكية: + + ```python + from crewai import LLM + + # CrewAI automatically handles: + # 1. Token counting and tracking + # 2. Content summarization when needed + # 3. Task splitting for large contexts + + llm = LLM( + model="gpt-4", + max_tokens=4000, # Limit response length + ) + ``` + + + أفضل الممارسات لإدارة السياق: + 1. اختر نماذج بنوافذ سياق مناسبة + 2. عالج المدخلات الطويلة مسبقًا عند الإمكان + 3. استخدم التقسيم للمستندات الكبيرة + 4. راقب استخدام الرموز لتحسين التكاليف + + + + + + + اختر نافذة السياق المناسبة لمهمتك: + - المهام الصغيرة (حتى 4K رمز): النماذج القياسية + - المهام المتوسطة (بين 4K-32K): النماذج المحسّنة + - المهام الكبيرة (أكثر من 32K): نماذج السياق الكبير + + ```python + # Configure model with appropriate settings + llm = LLM( + model="openai/gpt-4-turbo-preview", + temperature=0.7, # Adjust based on task + max_tokens=4096, # Set based on output needs + timeout=300 # Longer timeout for complex tasks + ) + ``` + + - درجة حرارة منخفضة (0.1 إلى 0.3) للاستجابات الواقعية + - درجة حرارة عالية (0.7 إلى 0.9) للمهام الإبداعية + + + + + 1. راقب استخدام الرموز + 2. نفّذ تحديد المعدل + 3. استخدم التخزين المؤقت عند الإمكان + 4. عيّن حدود max_tokens مناسبة + + + + + تذكّر مراقبة استخدام الرموز بانتظام وضبط إعداداتك حسب الحاجة لتحسين التكاليف والأداء. + + + + + يستخدم CrewAI داخليًا حزم SDK أصلية لاستدعاءات LLM، مما يتيح لك إسقاط معاملات إضافية غير مطلوبة لحالة الاستخدام الخاصة بك. يمكن أن يساعد هذا في تبسيط كودك وتقليل تعقيد إعداد LLM. + + ```python + from crewai import LLM + import os + + os.environ["OPENAI_API_KEY"] = "" + + o3_llm = LLM( + model="o3", + drop_params=True, + additional_drop_params=["stop"] + ) + ``` + + + + يوفر CrewAI معترضات رسائل لعدة مزودين، مما يتيح لك الربط بدورات الطلب/الاستجابة على مستوى طبقة النقل. + + **المزودون المدعومون:** + - OpenAI + - Anthropic + + **الاستخدام الأساسي:** + ```python +import httpx +from crewai import LLM +from crewai.llms.hooks import BaseInterceptor + +class CustomInterceptor(BaseInterceptor[httpx.Request, httpx.Response]): + """Custom interceptor to modify requests and responses.""" + + def on_outbound(self, request: httpx.Request) -> httpx.Request: + """Print request before sending to the LLM provider.""" + print(request) + return request + + def on_inbound(self, response: httpx.Response) -> httpx.Response: + """Process response after receiving from the LLM provider.""" + print(f"Status: {response.status_code}") + print(f"Response time: {response.elapsed}") + return response + +# Use the interceptor with an LLM +llm = LLM( + model="openai/gpt-4o", + interceptor=CustomInterceptor() +) + ``` + + **ملاحظات مهمة:** + - يجب على كلتا الدالتين إعادة الكائن المستلم أو نوعه. + - تعديل الكائنات المستلمة قد يؤدي إلى سلوك غير متوقع أو أعطال في التطبيق. + - ليس كل المزودين يدعمون المعترضات -- تحقق من قائمة المزودين المدعومين أعلاه + + + تعمل المعترضات على مستوى طبقة النقل. مفيدة بشكل خاص لـ: + - تحويل الرسائل وتصفيتها + - تصحيح تفاعلات API + + + + +## المشاكل الشائعة والحلول + + + + + يمكن حل معظم مشاكل المصادقة بالتحقق من تنسيق مفتاح API وأسماء متغيرات البيئة. + + + ```bash + # OpenAI + OPENAI_API_KEY=sk-... + + # Anthropic + ANTHROPIC_API_KEY=sk-ant-... + ``` + + + + ضمّن دائمًا بادئة المزود في أسماء النماذج + + + ```python + # Correct + llm = LLM(model="openai/gpt-4") + + # Incorrect + llm = LLM(model="gpt-4") + ``` + + + + استخدم نماذج سياق أكبر للمهام الواسعة + + + ```python + # Large context model + llm = LLM(model="openai/gpt-4o") # 128K tokens + ``` + + diff --git a/docs/ar/concepts/memory.mdx b/docs/ar/concepts/memory.mdx new file mode 100644 index 000000000..541f2967a --- /dev/null +++ b/docs/ar/concepts/memory.mdx @@ -0,0 +1,878 @@ +--- +title: الذاكرة +description: الاستفادة من نظام الذاكرة الموحد في CrewAI لتعزيز قدرات الوكلاء. +icon: database +mode: "wide" +--- + +## نظرة عامة + +يوفر CrewAI **نظام ذاكرة موحد** -- فئة `Memory` واحدة تستبدل أنواع الذاكرة المنفصلة (قصيرة المدى، طويلة المدى، ذاكرة الكيانات، والخارجية) بواجهة برمجة تطبيقات ذكية واحدة. تستخدم الذاكرة LLM لتحليل المحتوى عند الحفظ (استنتاج النطاق والفئات والأهمية) وتدعم الاسترجاع متعدد العمق مع تسجيل مركب يمزج بين التشابه الدلالي والحداثة والأهمية. + +يمكنك استخدام الذاكرة بأربع طرق: **مستقلة** (سكربتات، دفاتر ملاحظات)، **مع فرق Crew**، **مع Agents**، أو **داخل التدفقات**. + +## البدء السريع + +```python +from crewai import Memory + +memory = Memory() + +# Store -- the LLM infers scope, categories, and importance +memory.remember("We decided to use PostgreSQL for the user database.") + +# Retrieve -- results ranked by composite score (semantic + recency + importance) +matches = memory.recall("What database did we choose?") +for m in matches: + print(f"[{m.score:.2f}] {m.record.content}") + +# Tune scoring for a fast-moving project +memory = Memory(recency_weight=0.5, recency_half_life_days=7) + +# Forget +memory.forget(scope="/project/old") + +# Explore the self-organized scope tree +print(memory.tree()) +print(memory.info("/")) +``` + +## أربع طرق لاستخدام الذاكرة + +### مستقلة + +استخدم الذاكرة في السكربتات ودفاتر الملاحظات وأدوات سطر الأوامر أو كقاعدة معرفة مستقلة -- لا حاجة لوكلاء أو فرق Crew. + +```python +from crewai import Memory + +memory = Memory() + +# Build up knowledge +memory.remember("The API rate limit is 1000 requests per minute.") +memory.remember("Our staging environment uses port 8080.") +memory.remember("The team agreed to use feature flags for all new releases.") + +# Later, recall what you need +matches = memory.recall("What are our API limits?", limit=5) +for m in matches: + print(f"[{m.score:.2f}] {m.record.content}") + +# Extract atomic facts from a longer text +raw = """Meeting notes: We decided to migrate from MySQL to PostgreSQL +next quarter. The budget is $50k. Sarah will lead the migration.""" + +facts = memory.extract_memories(raw) +# ["Migration from MySQL to PostgreSQL planned for next quarter", +# "Database migration budget is $50k", +# "Sarah will lead the database migration"] + +for fact in facts: + memory.remember(fact) +``` + +### مع فرق Crew + +مرّر `memory=True` للإعدادات الافتراضية، أو مرّر مثيل `Memory` مُعدّ للسلوك المخصص. + +```python +from crewai import Crew, Agent, Task, Process, Memory + +# Option 1: Default memory +crew = Crew( + agents=[researcher, writer], + tasks=[research_task, writing_task], + process=Process.sequential, + memory=True, + verbose=True, +) + +# Option 2: Custom memory with tuned scoring +memory = Memory( + recency_weight=0.4, + semantic_weight=0.4, + importance_weight=0.2, + recency_half_life_days=14, +) +crew = Crew( + agents=[researcher, writer], + tasks=[research_task, writing_task], + memory=memory, +) +``` + +عند استخدام `memory=True`، ينشئ الفريق مثيل `Memory()` افتراضيًا ويمرر إعداد `embedder` الخاص بالفريق تلقائيًا. يشترك جميع الوكلاء في الفريق في ذاكرة الفريق ما لم يكن لدى الوكيل ذاكرته الخاصة. + +بعد كل مهمة، يستخرج الفريق تلقائيًا حقائق منفصلة من مخرجات المهمة ويخزّنها. قبل كل مهمة، يسترجع الوكيل السياق ذا الصلة من الذاكرة ويحقنه في موجّه المهمة. + +### مع Agents + +يمكن للوكلاء استخدام ذاكرة الفريق المشتركة (افتراضيًا) أو تلقي عرض محدد النطاق للسياق الخاص. + +```python +from crewai import Agent, Memory + +memory = Memory() + +# Researcher gets a private scope -- only sees /agent/researcher +researcher = Agent( + role="Researcher", + goal="Find and analyze information", + backstory="Expert researcher with attention to detail", + memory=memory.scope("/agent/researcher"), +) + +# Writer uses crew shared memory (no agent-level memory set) +writer = Agent( + role="Writer", + goal="Produce clear, well-structured content", + backstory="Experienced technical writer", + # memory not set -- uses crew._memory when crew has memory enabled +) +``` + +يمنح هذا النمط الباحث نتائج خاصة بينما يقرأ الكاتب من ذاكرة الفريق المشتركة. + +### مع التدفقات + +كل تدفق يحتوي على ذاكرة مدمجة. استخدم `self.remember()` و `self.recall()` و `self.extract_memories()` داخل أي دالة تدفق. + +```python +from crewai.flow.flow import Flow, listen, start + +class ResearchFlow(Flow): + @start() + def gather_data(self): + findings = "PostgreSQL handles 10k concurrent connections. MySQL caps at 5k." + self.remember(findings, scope="/research/databases") + return findings + + @listen(gather_data) + def write_report(self, findings): + # Recall past research to provide context + past = self.recall("database performance benchmarks") + context = "\n".join(f"- {m.record.content}" for m in past) + return f"Report:\nNew findings: {findings}\nPrevious context:\n{context}" +``` + +انظر [وثائق التدفقات](/concepts/flows) لمزيد من المعلومات حول الذاكرة في التدفقات. + + +## النطاقات الهرمية + +### ما هي النطاقات + +يتم تنظيم الذكريات في شجرة هرمية من النطاقات، مشابهة لنظام الملفات. كل نطاق هو مسار مثل `/` أو `/project/alpha` أو `/agent/researcher/findings`. + +``` +/ + /company + /company/engineering + /company/product + /project + /project/alpha + /project/beta + /agent + /agent/researcher + /agent/writer +``` + +توفر النطاقات **ذاكرة تعتمد على السياق** -- عند الاسترجاع ضمن نطاق، تبحث فقط في ذلك الفرع من الشجرة، مما يحسّن كلًا من الدقة والأداء. + +### كيف يعمل استنتاج النطاق + +عند استدعاء `remember()` دون تحديد نطاق، يحلل LLM المحتوى وشجرة النطاقات الحالية، ثم يقترح أفضل موضع. إذا لم يكن هناك نطاق حالي مناسب، ينشئ واحدًا جديدًا. بمرور الوقت، تنمو شجرة النطاقات عضويًا من المحتوى نفسه -- لا تحتاج إلى تصميم مخطط مسبقًا. + +```python +memory = Memory() + +# LLM infers scope from content +memory.remember("We chose PostgreSQL for the user database.") +# -> might be placed under /project/decisions or /engineering/database + +# You can also specify scope explicitly +memory.remember("Sprint velocity is 42 points", scope="/team/metrics") +``` + +### تصوير شجرة النطاقات + +```python +print(memory.tree()) +# / (15 records) +# /project (8 records) +# /project/alpha (5 records) +# /project/beta (3 records) +# /agent (7 records) +# /agent/researcher (4 records) +# /agent/writer (3 records) + +print(memory.info("/project/alpha")) +# ScopeInfo(path='/project/alpha', record_count=5, +# categories=['architecture', 'database'], +# oldest_record=datetime(...), newest_record=datetime(...), +# child_scopes=[]) +``` + +### MemoryScope: عروض الأشجار الفرعية + +يقيّد `MemoryScope` جميع العمليات على فرع من الشجرة. يمكن للوكيل أو الكود الذي يستخدمه الرؤية والكتابة فقط ضمن تلك الشجرة الفرعية. + +```python +memory = Memory() + +# Create a scope for a specific agent +agent_memory = memory.scope("/agent/researcher") + +# Everything is relative to /agent/researcher +agent_memory.remember("Found three relevant papers on LLM memory.") +# -> stored under /agent/researcher + +agent_memory.recall("relevant papers") +# -> searches only under /agent/researcher + +# Narrow further with subscope +project_memory = agent_memory.subscope("project-alpha") +# -> /agent/researcher/project-alpha +``` + +### أفضل الممارسات لتصميم النطاقات + +- **ابدأ بشكل مسطح، ودع LLM ينظّم.** لا تبالغ في هندسة تسلسل النطاقات مسبقًا. ابدأ بـ `memory.remember(content)` ودع استنتاج النطاق في LLM ينشئ الهيكل مع تراكم المحتوى. + +- **استخدم أنماط `/{entity_type}/{identifier}`.** تنشأ التسلسلات الطبيعية من أنماط مثل `/project/alpha` و `/agent/researcher` و `/company/engineering` و `/customer/acme-corp`. + +- **حدد النطاق حسب الاهتمام، وليس حسب نوع البيانات.** استخدم `/project/alpha/decisions` بدلاً من `/decisions/project/alpha`. هذا يبقي المحتوى ذا الصلة معًا. + +- **حافظ على العمق ضحلًا (2-3 مستويات).** النطاقات المتداخلة بعمق تصبح متفرقة جدًا. `/project/alpha/architecture` جيد؛ `/project/alpha/architecture/decisions/databases/postgresql` عميق جدًا. + +- **استخدم النطاقات الصريحة عندما تعرف، ودع LLM يستنتج عندما لا تعرف.** إذا كنت تخزّن قرار مشروع معروف، مرّر `scope="/project/alpha/decisions"`. إذا كنت تخزّن مخرجات وكيل حرة الشكل، اترك النطاق ودع LLM يحدده. + +### أمثلة حالات الاستخدام + +**فريق متعدد المشاريع:** +```python +memory = Memory() +# Each project gets its own branch +memory.remember("Using microservices architecture", scope="/project/alpha/architecture") +memory.remember("GraphQL API for client apps", scope="/project/beta/api") + +# Recall across all projects +memory.recall("API design decisions") + +# Or within a specific project +memory.recall("API design", scope="/project/beta") +``` + +**سياق خاص لكل وكيل مع معرفة مشتركة:** +```python +memory = Memory() + +# Researcher has private findings +researcher_memory = memory.scope("/agent/researcher") + +# Writer can read from both its own scope and shared company knowledge +writer_view = memory.slice( + scopes=["/agent/writer", "/company/knowledge"], + read_only=True, +) +``` + +**دعم العملاء (سياق لكل عميل):** +```python +memory = Memory() + +# Each customer gets isolated context +memory.remember("Prefers email communication", scope="/customer/acme-corp") +memory.remember("On enterprise plan, 50 seats", scope="/customer/acme-corp") + +# Shared product docs are accessible to all agents +memory.remember("Rate limit is 1000 req/min on enterprise plan", scope="/product/docs") +``` + + +## شرائح الذاكرة + +### ما هي الشرائح + +`MemorySlice` هو عرض عبر نطاقات متعددة، ربما متباعدة. على عكس النطاق (الذي يقيّد على شجرة فرعية واحدة)، تتيح لك الشريحة الاسترجاع من عدة فروع في وقت واحد. + +### متى تستخدم الشرائح مقابل النطاقات + +- **النطاق**: استخدمه عندما يجب تقييد وكيل أو كتلة كود على شجرة فرعية واحدة. مثال: وكيل يرى فقط `/agent/researcher`. +- **الشريحة**: استخدمها عندما تحتاج إلى دمج السياق من عدة فروع. مثال: وكيل يقرأ من نطاقه الخاص بالإضافة إلى معرفة الشركة المشتركة. + +### شرائح القراءة فقط + +النمط الأكثر شيوعًا: منح وكيل إمكانية القراءة من فروع متعددة دون السماح له بالكتابة في المناطق المشتركة. + +```python +memory = Memory() + +# Agent can recall from its own scope AND company knowledge, +# but cannot write to company knowledge +agent_view = memory.slice( + scopes=["/agent/researcher", "/company/knowledge"], + read_only=True, +) + +matches = agent_view.recall("company security policies", limit=5) +# Searches both /agent/researcher and /company/knowledge, merges and ranks results + +agent_view.remember("new finding") # Raises PermissionError (read-only) +``` + +### شرائح القراءة والكتابة + +عند تعطيل القراءة فقط، يمكنك الكتابة في أي من النطاقات المضمّنة، لكن يجب تحديد النطاق صراحة. + +```python +view = memory.slice(scopes=["/team/alpha", "/team/beta"], read_only=False) + +# Must specify scope when writing +view.remember("Cross-team decision", scope="/team/alpha", categories=["decisions"]) +``` + + +## التسجيل المركب + +يتم ترتيب نتائج الاسترجاع بواسطة مزيج مرجّح من ثلاث إشارات: + +``` +composite = semantic_weight * similarity + recency_weight * decay + importance_weight * importance +``` + +حيث: +- **similarity** = `1 / (1 + distance)` من فهرس المتجهات (0 إلى 1) +- **decay** = `0.5^(age_days / half_life_days)` -- اضمحلال أُسي (1.0 لليوم، 0.5 عند نصف العمر) +- **importance** = درجة أهمية السجل (0 إلى 1)، يتم تعيينها وقت الترميز + +قم بإعدادها مباشرة على منشئ `Memory`: + +```python +# Sprint retrospective: favor recent memories, short half-life +memory = Memory( + recency_weight=0.5, + semantic_weight=0.3, + importance_weight=0.2, + recency_half_life_days=7, +) + +# Architecture knowledge base: favor important memories, long half-life +memory = Memory( + recency_weight=0.1, + semantic_weight=0.5, + importance_weight=0.4, + recency_half_life_days=180, +) +``` + +يتضمن كل `MemoryMatch` قائمة `match_reasons` حتى تتمكن من رؤية سبب ترتيب نتيجة معينة في موضعها (مثل `["semantic", "recency", "importance"]`). + + +## طبقة تحليل LLM + +تستخدم الذاكرة LLM بثلاث طرق: + +1. **عند الحفظ** -- عندما تحذف النطاق أو الفئات أو الأهمية، يحلل LLM المحتوى ويقترح النطاق والفئات والأهمية والبيانات الوصفية (الكيانات والتواريخ والموضوعات). +2. **عند الاسترجاع** -- للاسترجاع العميق/التلقائي، يحلل LLM الاستعلام (الكلمات المفتاحية، تلميحات الوقت، النطاقات المقترحة، التعقيد) لتوجيه الاسترجاع. +3. **استخراج الذكريات** -- `extract_memories(content)` يقسم النص الخام (مثل مخرجات المهمة) إلى عبارات ذاكرة منفصلة. يستخدم الوكلاء هذا قبل استدعاء `remember()` على كل عبارة حتى يتم تخزين حقائق ذرية بدلاً من كتلة كبيرة واحدة. + +جميع التحليلات تتدهور بسلاسة عند فشل LLM -- انظر [سلوك الفشل](#سلوك-الفشل). + + +## توحيد الذاكرة + +عند حفظ محتوى جديد، يتحقق خط أنابيب الترميز تلقائيًا من وجود سجلات مماثلة في التخزين. إذا كان التشابه أعلى من `consolidation_threshold` (الافتراضي 0.85)، يقرر LLM ما يجب فعله: + +- **keep** -- السجل الحالي لا يزال دقيقًا وغير مكرر. +- **update** -- يجب تحديث السجل الحالي بمعلومات جديدة (يوفر LLM المحتوى المدمج). +- **delete** -- السجل الحالي قديم أو تم استبداله أو تناقضه. +- **insert_new** -- ما إذا كان يجب إدراج المحتوى الجديد أيضًا كسجل منفصل. + +هذا يمنع تراكم النسخ المكررة. على سبيل المثال، إذا حفظت "CrewAI ensures reliable operation" ثلاث مرات، يتعرف التوحيد على النسخ المكررة ويحتفظ بسجل واحد فقط. + +### إزالة التكرار داخل الدفعة + +عند استخدام `remember_many()`، تتم مقارنة العناصر داخل نفس الدفعة مع بعضها البعض قبل الوصول إلى التخزين. إذا كان تشابه جيب التمام >= `batch_dedup_threshold` (الافتراضي 0.98)، يتم إسقاط العنصر الأحدث بصمت. هذا يلتقط النسخ المكررة الدقيقة أو شبه الدقيقة داخل دفعة واحدة دون أي استدعاءات LLM (رياضيات متجهات خالصة). + +```python +# Only 2 records are stored (the third is a near-duplicate of the first) +memory.remember_many([ + "CrewAI supports complex workflows.", + "Python is a great language.", + "CrewAI supports complex workflows.", # dropped by intra-batch dedup +]) +``` + + +## الحفظ غير الحاجب + +`remember_many()` **غير حاجب** -- يقدم خط أنابيب الترميز إلى خيط خلفي ويعود فورًا. هذا يعني أن الوكيل يمكنه المتابعة إلى المهمة التالية بينما يتم حفظ الذكريات. + +```python +# Returns immediately -- save happens in background +memory.remember_many(["Fact A.", "Fact B.", "Fact C."]) + +# recall() automatically waits for pending saves before searching +matches = memory.recall("facts") # sees all 3 records +``` + +### حاجز القراءة + +كل استدعاء `recall()` يستدعي تلقائيًا `drain_writes()` قبل البحث، مما يضمن أن الاستعلام يرى دائمًا أحدث السجلات المستمرة. هذا شفاف -- لا تحتاج أبدًا إلى التفكير فيه. + +### إيقاف الفريق + +عند انتهاء الفريق، يستنزف `kickoff()` جميع عمليات حفظ الذاكرة المعلقة في كتلة `finally` الخاصة به، لذا لا تُفقد أي عمليات حفظ حتى لو اكتمل الفريق بينما عمليات الحفظ الخلفية قيد التنفيذ. + +### الاستخدام المستقل + +للسكربتات أو دفاتر الملاحظات حيث لا توجد دورة حياة فريق، استدعِ `drain_writes()` أو `close()` صراحة: + +```python +memory = Memory() +memory.remember_many(["Fact A.", "Fact B."]) + +# Option 1: Wait for pending saves +memory.drain_writes() + +# Option 2: Drain and shut down the background pool +memory.close() +``` + + +## المصدر والخصوصية + +يمكن لكل سجل ذاكرة أن يحمل علامة `source` لتتبع المصدر وعلامة `private` للتحكم في الوصول. + +### تتبع المصدر + +يحدد معامل `source` من أين جاءت الذاكرة: + +```python +# Tag memories with their origin +memory.remember("User prefers dark mode", source="user:alice") +memory.remember("System config updated", source="admin") +memory.remember("Agent found a bug", source="agent:debugger") + +# Recall only memories from a specific source +matches = memory.recall("user preferences", source="user:alice") +``` + +### الذكريات الخاصة + +الذكريات الخاصة مرئية فقط للاسترجاع عندما يتطابق `source`: + +```python +# Store a private memory +memory.remember("Alice's API key is sk-...", source="user:alice", private=True) + +# This recall sees the private memory (source matches) +matches = memory.recall("API key", source="user:alice") + +# This recall does NOT see it (different source) +matches = memory.recall("API key", source="user:bob") + +# Admin access: see all private records regardless of source +matches = memory.recall("API key", include_private=True) +``` + +هذا مفيد بشكل خاص في النشرات متعددة المستخدمين أو المؤسسية حيث يجب عزل ذكريات المستخدمين المختلفين. + + +## RecallFlow (الاسترجاع العميق) + +يدعم `recall()` عمقين: + +- **`depth="shallow"`** -- بحث متجهي مباشر مع تسجيل مركب. سريع (~200 مللي ثانية)، بدون استدعاءات LLM. +- **`depth="deep"` (افتراضي)** -- يشغل RecallFlow متعدد الخطوات: تحليل الاستعلام، اختيار النطاق، بحث متجهي متوازٍ، توجيه قائم على الثقة، واستكشاف متكرر اختياري عندما تكون الثقة منخفضة. + +**تخطي LLM الذكي**: الاستعلامات الأقصر من `query_analysis_threshold` (الافتراضي 200 حرف) تتخطى تحليل LLM للاستعلام بالكامل، حتى في الوضع العميق. الاستعلامات القصيرة مثل "ما قاعدة البيانات التي نستخدمها؟" هي بالفعل عبارات بحث جيدة -- تحليل LLM يضيف قيمة قليلة. هذا يوفر ~1-3 ثوانٍ لكل استرجاع للاستعلامات القصيرة النموذجية. فقط الاستعلامات الأطول (مثل أوصاف المهام الكاملة) تمر عبر تقطير LLM إلى استعلامات فرعية مستهدفة. + +```python +# Shallow: pure vector search, no LLM +matches = memory.recall("What did we decide?", limit=10, depth="shallow") + +# Deep (default): intelligent retrieval with LLM analysis for long queries +matches = memory.recall( + "Summarize all architecture decisions from this quarter", + limit=10, + depth="deep", +) +``` + +عتبات الثقة التي تتحكم في موجّه RecallFlow قابلة للإعداد: + +```python +memory = Memory( + confidence_threshold_high=0.9, # Only synthesize when very confident + confidence_threshold_low=0.4, # Explore deeper more aggressively + exploration_budget=2, # Allow up to 2 exploration rounds + query_analysis_threshold=200, # Skip LLM for queries shorter than this +) +``` + + +## إعداد المُضمِّن + +تحتاج الذاكرة إلى نموذج تضمين لتحويل النص إلى متجهات للبحث الدلالي. يمكنك إعداده بثلاث طرق. + +### التمرير إلى Memory مباشرة + +```python +from crewai import Memory + +# As a config dict +memory = Memory(embedder={"provider": "openai", "config": {"model_name": "text-embedding-3-small"}}) + +# As a pre-built callable +from crewai.rag.embeddings.factory import build_embedder +embedder = build_embedder({"provider": "ollama", "config": {"model_name": "mxbai-embed-large"}}) +memory = Memory(embedder=embedder) +``` + +### عبر إعداد مُضمِّن Crew + +عند استخدام `memory=True`، يتم تمرير إعداد `embedder` الخاص بالفريق: + +```python +from crewai import Crew + +crew = Crew( + agents=[...], + tasks=[...], + memory=True, + embedder={"provider": "openai", "config": {"model_name": "text-embedding-3-small"}}, +) +``` + +### أمثلة المزودين + + + +```python +memory = Memory(embedder={ + "provider": "openai", + "config": { + "model_name": "text-embedding-3-small", + # "api_key": "sk-...", # or set OPENAI_API_KEY env var + }, +}) +``` + + + +```python +memory = Memory(embedder={ + "provider": "ollama", + "config": { + "model_name": "mxbai-embed-large", + "url": "http://localhost:11434/api/embeddings", + }, +}) +``` + + + +```python +memory = Memory(embedder={ + "provider": "azure", + "config": { + "deployment_id": "your-embedding-deployment", + "api_key": "your-azure-api-key", + "api_base": "https://your-resource.openai.azure.com", + "api_version": "2024-02-01", + }, +}) +``` + + + +```python +memory = Memory(embedder={ + "provider": "google-generativeai", + "config": { + "model_name": "gemini-embedding-001", + # "api_key": "...", # or set GOOGLE_API_KEY env var + }, +}) +``` + + + +```python +memory = Memory(embedder={ + "provider": "google-vertex", + "config": { + "model_name": "gemini-embedding-001", + "project_id": "your-gcp-project-id", + "location": "us-central1", + }, +}) +``` + + + +```python +memory = Memory(embedder={ + "provider": "cohere", + "config": { + "model_name": "embed-english-v3.0", + # "api_key": "...", # or set COHERE_API_KEY env var + }, +}) +``` + + + +```python +memory = Memory(embedder={ + "provider": "voyageai", + "config": { + "model": "voyage-3", + # "api_key": "...", # or set VOYAGE_API_KEY env var + }, +}) +``` + + + +```python +memory = Memory(embedder={ + "provider": "amazon-bedrock", + "config": { + "model_name": "amazon.titan-embed-text-v1", + # Uses default AWS credentials (boto3 session) + }, +}) +``` + + + +```python +memory = Memory(embedder={ + "provider": "huggingface", + "config": { + "model_name": "sentence-transformers/all-MiniLM-L6-v2", + }, +}) +``` + + + +```python +memory = Memory(embedder={ + "provider": "jina", + "config": { + "model_name": "jina-embeddings-v2-base-en", + # "api_key": "...", # or set JINA_API_KEY env var + }, +}) +``` + + + +```python +memory = Memory(embedder={ + "provider": "watsonx", + "config": { + "model_id": "ibm/slate-30m-english-rtrvr", + "api_key": "your-watsonx-api-key", + "project_id": "your-project-id", + "url": "https://us-south.ml.cloud.ibm.com", + }, +}) +``` + + + +```python +# Pass any callable that takes a list of strings and returns a list of vectors +def my_embedder(texts: list[str]) -> list[list[float]]: + # Your embedding logic here + return [[0.1, 0.2, ...] for _ in texts] + +memory = Memory(embedder=my_embedder) +``` + + + +### مرجع المزودين + +| المزود | المفتاح | النموذج النموذجي | ملاحظات | +| :--- | :--- | :--- | :--- | +| OpenAI | `openai` | `text-embedding-3-small` | افتراضي. عيّن `OPENAI_API_KEY`. | +| Ollama | `ollama` | `mxbai-embed-large` | محلي، لا حاجة لمفتاح API. | +| Azure OpenAI | `azure` | `text-embedding-ada-002` | يتطلب `deployment_id`. | +| Google AI | `google-generativeai` | `gemini-embedding-001` | عيّن `GOOGLE_API_KEY`. | +| Google Vertex | `google-vertex` | `gemini-embedding-001` | يتطلب `project_id`. | +| Cohere | `cohere` | `embed-english-v3.0` | دعم قوي متعدد اللغات. | +| VoyageAI | `voyageai` | `voyage-3` | محسّن للاسترجاع. | +| AWS Bedrock | `amazon-bedrock` | `amazon.titan-embed-text-v1` | يستخدم بيانات اعتماد boto3. | +| Hugging Face | `huggingface` | `all-MiniLM-L6-v2` | sentence-transformers محلي. | +| Jina | `jina` | `jina-embeddings-v2-base-en` | عيّن `JINA_API_KEY`. | +| IBM WatsonX | `watsonx` | `ibm/slate-30m-english-rtrvr` | يتطلب `project_id`. | +| Sentence Transformer | `sentence-transformer` | `all-MiniLM-L6-v2` | محلي، لا حاجة لمفتاح API. | +| مخصص | `custom` | -- | يتطلب `embedding_callable`. | + + +## إعداد LLM + +تستخدم الذاكرة LLM لتحليل الحفظ (استنتاج النطاق والفئات والأهمية)، وقرارات التوحيد، وتحليل استعلام الاسترجاع العميق. يمكنك إعداد النموذج المُستخدم. + +```python +from crewai import Memory, LLM + +# Default: gpt-4o-mini +memory = Memory() + +# Use a different OpenAI model +memory = Memory(llm="gpt-4o") + +# Use Anthropic +memory = Memory(llm="anthropic/claude-3-haiku-20240307") + +# Use Ollama for fully local/private analysis +memory = Memory(llm="ollama/llama3.2") + +# Use Google Gemini +memory = Memory(llm="gemini/gemini-2.0-flash") + +# Pass a pre-configured LLM instance with custom settings +llm = LLM(model="gpt-4o", temperature=0) +memory = Memory(llm=llm) +``` + +يتم تهيئة LLM **بشكل كسول** -- يتم إنشاؤه فقط عند الحاجة لأول مرة. هذا يعني أن `Memory()` لا يفشل أبدًا في وقت الإنشاء، حتى لو لم تكن مفاتيح API مُعيّنة. تظهر الأخطاء فقط عند استدعاء LLM فعليًا (مثلاً عند الحفظ بدون نطاق/فئات صريحة، أو أثناء الاسترجاع العميق). + +للتشغيل المحلي/الخاص بالكامل، استخدم نموذجًا محليًا لكل من LLM والمُضمِّن: + +```python +memory = Memory( + llm="ollama/llama3.2", + embedder={"provider": "ollama", "config": {"model_name": "mxbai-embed-large"}}, +) +``` + + +## واجهة التخزين + +- **الافتراضي**: LanceDB، مخزّن تحت `./.crewai/memory` (أو `$CREWAI_STORAGE_DIR/memory` إذا تم تعيين متغير البيئة، أو المسار الذي تمرره كـ `storage="path/to/dir"`). +- **واجهة مخصصة**: نفّذ بروتوكول `StorageBackend` (انظر `crewai.memory.storage.backend`) ومرّر مثيلًا إلى `Memory(storage=your_backend)`. + + +## الاستكشاف + +فحص التسلسل الهرمي للنطاقات والفئات والسجلات: + +```python +memory.tree() # Formatted tree of scopes and record counts +memory.tree("/project", max_depth=2) # Subtree view +memory.info("/project") # ScopeInfo: record_count, categories, oldest/newest +memory.list_scopes("/") # Immediate child scopes +memory.list_categories() # Category names and counts +memory.list_records(scope="/project/alpha", limit=20) # Records in a scope, newest first +``` + + +## سلوك الفشل + +إذا فشل LLM أثناء التحليل (خطأ شبكة، حد معدل، استجابة غير صالحة)، تتدهور الذاكرة بسلاسة: + +- **تحليل الحفظ** -- يتم تسجيل تحذير ولا يزال يتم تخزين الذاكرة مع النطاق الافتراضي `/`، فئات فارغة، وأهمية `0.5`. +- **استخراج الذكريات** -- يتم تخزين المحتوى الكامل كذاكرة واحدة حتى لا يُفقد شيء. +- **تحليل الاستعلام** -- يتراجع الاسترجاع إلى اختيار نطاق بسيط وبحث متجهي حتى تستمر في الحصول على نتائج. + +لا يتم رفع أي استثناء لفشل التحليل هذه؛ فقط فشل التخزين أو المُضمِّن سيرفع استثناءً. + + +## ملاحظة حول الخصوصية + +يتم إرسال محتوى الذاكرة إلى LLM المُعدّ للتحليل (النطاق/الفئات/الأهمية عند الحفظ، تحليل الاستعلام والاسترجاع العميق الاختياري). للبيانات الحساسة، استخدم LLM محليًا (مثل Ollama) أو تأكد من أن مزودك يلبي متطلبات الامتثال الخاصة بك. + + +## أحداث الذاكرة + +جميع عمليات الذاكرة تُصدر أحداثًا مع `source_type="unified_memory"`. يمكنك الاستماع للتوقيت والأخطاء والمحتوى. + +| الحدث | الوصف | الخصائص الرئيسية | +| :---- | :---------- | :------------- | +| **MemoryQueryStartedEvent** | بداية الاستعلام | `query`, `limit` | +| **MemoryQueryCompletedEvent** | نجاح الاستعلام | `query`, `results`, `query_time_ms` | +| **MemoryQueryFailedEvent** | فشل الاستعلام | `query`, `error` | +| **MemorySaveStartedEvent** | بداية الحفظ | `value`, `metadata` | +| **MemorySaveCompletedEvent** | نجاح الحفظ | `value`, `save_time_ms` | +| **MemorySaveFailedEvent** | فشل الحفظ | `value`, `error` | +| **MemoryRetrievalStartedEvent** | بداية استرجاع الوكيل | `task_id` | +| **MemoryRetrievalCompletedEvent** | اكتمال استرجاع الوكيل | `task_id`, `memory_content`, `retrieval_time_ms` | + +مثال: مراقبة وقت الاستعلام: + +```python +from crewai.events import BaseEventListener, MemoryQueryCompletedEvent + +class MemoryMonitor(BaseEventListener): + def setup_listeners(self, crewai_event_bus): + @crewai_event_bus.on(MemoryQueryCompletedEvent) + def on_done(source, event): + if getattr(event, "source_type", None) == "unified_memory": + print(f"Query '{event.query}' completed in {event.query_time_ms:.0f}ms") +``` + + +## استكشاف المشاكل + +**الذاكرة لا تستمر؟** +- تأكد من أن مسار التخزين قابل للكتابة (الافتراضي `./.crewai/memory`). مرّر `storage="./your_path"` لاستخدام مجلد مختلف، أو عيّن متغير البيئة `CREWAI_STORAGE_DIR`. +- عند استخدام فريق، تأكد من تعيين `memory=True` أو `memory=Memory(...)`. + +**الاسترجاع بطيء؟** +- استخدم `depth="shallow"` لسياق الوكيل الروتيني. احتفظ بـ `depth="deep"` للاستعلامات المعقدة. +- زد `query_analysis_threshold` لتخطي تحليل LLM لمزيد من الاستعلامات. + +**أخطاء تحليل LLM في السجلات؟** +- لا تزال الذاكرة تحفظ/تسترجع بإعدادات افتراضية آمنة. تحقق من مفاتيح API وحدود المعدل وتوفر النموذج إذا كنت تريد تحليل LLM كاملاً. + +**أخطاء حفظ خلفية في السجلات؟** +- عمليات حفظ الذاكرة تعمل في خيط خلفي. تُصدر الأخطاء كـ `MemorySaveFailedEvent` لكنها لا تعطل الوكيل. تحقق من السجلات للسبب الجذري (عادة مشاكل اتصال LLM أو المُضمِّن). + +**تعارضات الكتابة المتزامنة؟** +- عمليات LanceDB مُتسلسلة بقفل مشترك وتُعاد تلقائيًا عند التعارض. هذا يتعامل مع مثيلات `Memory` المتعددة التي تشير إلى نفس قاعدة البيانات (مثل ذاكرة وكيل + ذاكرة فريق). لا حاجة لإجراء. + +**تصفح الذاكرة من الطرفية:** +```bash +crewai memory # Opens the TUI browser +crewai memory --storage-path ./my_memory # Point to a specific directory +``` + +**إعادة تعيين الذاكرة (مثلاً للاختبارات):** +```python +crew.reset_memories(command_type="memory") # Resets unified memory +# Or on a Memory instance: +memory.reset() # All scopes +memory.reset(scope="/project/old") # Only that subtree +``` + + +## مرجع الإعداد + +جميع الإعدادات تُمرر كمعاملات كلمة مفتاحية إلى `Memory(...)`. كل معامل له قيمة افتراضية معقولة. + +| المعامل | الافتراضي | الوصف | +| :--- | :--- | :--- | +| `llm` | `"gpt-4o-mini"` | LLM للتحليل (اسم نموذج أو مثيل `BaseLLM`). | +| `storage` | `"lancedb"` | واجهة التخزين (`"lancedb"`، سلسلة مسار، أو مثيل `StorageBackend`). | +| `embedder` | `None` (افتراضي OpenAI) | المُضمِّن (قاموس إعداد، دالة قابلة للاستدعاء، أو `None` لافتراضي OpenAI). | +| `recency_weight` | `0.3` | وزن الحداثة في الدرجة المركبة. | +| `semantic_weight` | `0.5` | وزن التشابه الدلالي في الدرجة المركبة. | +| `importance_weight` | `0.2` | وزن الأهمية في الدرجة المركبة. | +| `recency_half_life_days` | `30` | أيام لتنصيف درجة الحداثة (اضمحلال أُسي). | +| `consolidation_threshold` | `0.85` | التشابه الذي يُشغّل فوقه التوحيد عند الحفظ. عيّن إلى `1.0` للتعطيل. | +| `consolidation_limit` | `5` | أقصى عدد سجلات حالية للمقارنة أثناء التوحيد. | +| `default_importance` | `0.5` | الأهمية المُعيّنة عندما لا تُوفَّر ويتم تخطي تحليل LLM. | +| `batch_dedup_threshold` | `0.98` | تشابه جيب التمام لإسقاط النسخ شبه المكررة داخل دفعة `remember_many()`. | +| `confidence_threshold_high` | `0.8` | ثقة الاسترجاع التي تُعاد فوقها النتائج مباشرة. | +| `confidence_threshold_low` | `0.5` | ثقة الاسترجاع التي يُشغّل تحتها استكشاف أعمق. | +| `complex_query_threshold` | `0.7` | للاستعلامات المعقدة، استكشف أعمق تحت هذه الثقة. | +| `exploration_budget` | `1` | عدد جولات الاستكشاف المدفوعة بـ LLM أثناء الاسترجاع العميق. | +| `query_analysis_threshold` | `200` | الاستعلامات الأقصر من هذا (بالأحرف) تتخطى تحليل LLM أثناء الاسترجاع العميق. | diff --git a/docs/ar/concepts/planning.mdx b/docs/ar/concepts/planning.mdx new file mode 100644 index 000000000..12f5ef117 --- /dev/null +++ b/docs/ar/concepts/planning.mdx @@ -0,0 +1,155 @@ +--- +title: التخطيط +description: تعرّف على كيفية إضافة التخطيط إلى طاقم CrewAI وتحسين أدائه. +icon: ruler-combined +mode: "wide" +--- + +## نظرة عامة + +تتيح لك ميزة التخطيط في CrewAI إضافة قدرة التخطيط إلى طاقمك. عند تفعيلها، قبل كل تكرار للطاقم، +يتم إرسال جميع معلومات الطاقم إلى AgentPlanner الذي يخطط للمهام خطوة بخطوة، ويُضاف هذا المخطط إلى وصف كل مهمة. + +### استخدام ميزة التخطيط + +البدء بميزة التخطيط سهل جدًا، الخطوة الوحيدة المطلوبة هي إضافة `planning=True` إلى طاقمك: + + +```python Code +from crewai import Crew, Agent, Task, Process + +# تجميع طاقمك مع قدرات التخطيط +my_crew = Crew( + agents=self.agents, + tasks=self.tasks, + process=Process.sequential, + planning=True, +) +``` + + +من هذه النقطة فصاعدًا، سيكون التخطيط مفعّلًا في طاقمك، وسيتم تخطيط المهام قبل كل تكرار. + + +عند تفعيل التخطيط، سيستخدم CrewAI `gpt-4o-mini` كنموذج LLM افتراضي للتخطيط، مما يتطلب مفتاح API صالحًا من OpenAI. نظرًا لأن وكلاءك قد يستخدمون نماذج LLM مختلفة، فقد يسبب ذلك ارتباكًا إذا لم يكن لديك مفتاح OpenAI API مهيأ أو إذا كنت تواجه سلوكًا غير متوقع متعلقًا باستدعاءات LLM API. + + +#### LLM التخطيط + +يمكنك الآن تحديد نموذج LLM الذي سيُستخدم لتخطيط المهام. + +عند تشغيل مثال الحالة الأساسية، سترى شيئًا مشابهًا للمخرجات أدناه، والتي تمثل مخرجات `AgentPlanner` +المسؤول عن إنشاء المنطق التدريجي لإضافته إلى مهام الوكلاء. + + +```python Code +from crewai import Crew, Agent, Task, Process + +# تجميع طاقمك مع قدرات التخطيط ونموذج LLM مخصص +my_crew = Crew( + agents=self.agents, + tasks=self.tasks, + process=Process.sequential, + planning=True, + planning_llm="gpt-4o" +) + +# تشغيل الطاقم +my_crew.kickoff() +``` + +```markdown Result +[2024-07-15 16:49:11][INFO]: Planning the crew execution +**Step-by-Step Plan for Task Execution** + +**Task Number 1: Conduct a thorough research about AI LLMs** + +**Agent:** AI LLMs Senior Data Researcher + +**Agent Goal:** Uncover cutting-edge developments in AI LLMs + +**Task Expected Output:** A list with 10 bullet points of the most relevant information about AI LLMs + +**Task Tools:** None specified + +**Agent Tools:** None specified + +**Step-by-Step Plan:** + +1. **Define Research Scope:** + + - Determine the specific areas of AI LLMs to focus on, such as advancements in architecture, use cases, ethical considerations, and performance metrics. + +2. **Identify Reliable Sources:** + + - List reputable sources for AI research, including academic journals, industry reports, conferences (e.g., NeurIPS, ACL), AI research labs (e.g., OpenAI, Google AI), and online databases (e.g., IEEE Xplore, arXiv). + +3. **Collect Data:** + + - Search for the latest papers, articles, and reports published in 2024 and early 2025. + - Use keywords like "Large Language Models 2025", "AI LLM advancements", "AI ethics 2025", etc. + +4. **Analyze Findings:** + + - Read and summarize the key points from each source. + - Highlight new techniques, models, and applications introduced in the past year. + +5. **Organize Information:** + + - Categorize the information into relevant topics (e.g., new architectures, ethical implications, real-world applications). + - Ensure each bullet point is concise but informative. + +6. **Create the List:** + + - Compile the 10 most relevant pieces of information into a bullet point list. + - Review the list to ensure clarity and relevance. + +**Expected Output:** + +A list with 10 bullet points of the most relevant information about AI LLMs. + +--- + +**Task Number 2: Review the context you got and expand each topic into a full section for a report** + +**Agent:** AI LLMs Reporting Analyst + +**Agent Goal:** Create detailed reports based on AI LLMs data analysis and research findings + +**Task Expected Output:** A fully fledged report with the main topics, each with a full section of information. Formatted as markdown without '```' + +**Task Tools:** None specified + +**Agent Tools:** None specified + +**Step-by-Step Plan:** + +1. **Review the Bullet Points:** + - Carefully read through the list of 10 bullet points provided by the AI LLMs Senior Data Researcher. + +2. **Outline the Report:** + - Create an outline with each bullet point as a main section heading. + - Plan sub-sections under each main heading to cover different aspects of the topic. + +3. **Research Further Details:** + - For each bullet point, conduct additional research if necessary to gather more detailed information. + - Look for case studies, examples, and statistical data to support each section. + +4. **Write Detailed Sections:** + - Expand each bullet point into a comprehensive section. + - Ensure each section includes an introduction, detailed explanation, examples, and a conclusion. + - Use markdown formatting for headings, subheadings, lists, and emphasis. + +5. **Review and Edit:** + - Proofread the report for clarity, coherence, and correctness. + - Make sure the report flows logically from one section to the next. + - Format the report according to markdown standards. + +6. **Finalize the Report:** + - Ensure the report is complete with all sections expanded and detailed. + - Double-check formatting and make any necessary adjustments. + +**Expected Output:** +A fully fledged report with the main topics, each with a full section of information. Formatted as markdown without '```'. +``` + diff --git a/docs/ar/concepts/processes.mdx b/docs/ar/concepts/processes.mdx new file mode 100644 index 000000000..211c219bc --- /dev/null +++ b/docs/ar/concepts/processes.mdx @@ -0,0 +1,67 @@ +--- +title: العمليات +description: دليل تفصيلي حول إدارة سير العمل من خلال العمليات في CrewAI، مع تفاصيل التنفيذ المحدّثة. +icon: bars-staggered +mode: "wide" +--- + +## نظرة عامة + + + تنسّق العمليات تنفيذ المهام بواسطة الوكلاء، على غرار إدارة المشاريع في الفرق البشرية. + تضمن هذه العمليات توزيع المهام وتنفيذها بكفاءة، وفقًا لاستراتيجية محددة مسبقًا. + + +## تنفيذات العمليات + +- **تسلسلي**: ينفذ المهام بالتتابع، مما يضمن إكمال المهام بتقدم منظم. +- **هرمي**: ينظم المهام في تسلسل إداري هرمي، حيث يتم تفويض المهام وتنفيذها بناءً على سلسلة أوامر منظمة. يجب تحديد نموذج لغة المدير (`manager_llm`) أو وكيل مدير مخصص (`manager_agent`) في الطاقم لتفعيل العملية الهرمية، مما يسهّل إنشاء وإدارة المهام من قبل المدير. +- **العملية التوافقية (مخطط لها)**: تهدف إلى اتخاذ القرارات بشكل تعاوني بين الوكلاء حول تنفيذ المهام، وتقدم هذه العملية نهجًا ديمقراطيًا لإدارة المهام داخل CrewAI. وهي مخطط لها للتطوير المستقبلي وغير مطبقة حاليًا في قاعدة الكود. + +## دور العمليات في العمل الجماعي +تُمكّن العمليات الوكلاء الأفراد من العمل كوحدة متماسكة، مما يبسّط جهودهم لتحقيق أهداف مشتركة بكفاءة وتناسق. + +## تعيين العمليات للطاقم +لتعيين عملية لطاقم، حدد نوع العملية عند إنشاء الطاقم لتعيين استراتيجية التنفيذ. للعملية الهرمية، تأكد من تحديد `manager_llm` أو `manager_agent` لوكيل المدير. + +```python +from crewai import Crew, Process + +# مثال: إنشاء طاقم بعملية تسلسلية +crew = Crew( + agents=my_agents, + tasks=my_tasks, + process=Process.sequential +) + +# مثال: إنشاء طاقم بعملية هرمية +# تأكد من توفير manager_llm أو manager_agent +crew = Crew( + agents=my_agents, + tasks=my_tasks, + process=Process.hierarchical, + manager_llm="gpt-4o" + # أو + # manager_agent=my_manager_agent +) +``` +**ملاحظة:** تأكد من تعريف `my_agents` و `my_tasks` قبل إنشاء كائن `Crew`، وللعملية الهرمية، يُعد `manager_llm` أو `manager_agent` مطلوبًا أيضًا. + +## العملية التسلسلية + +تعكس هذه الطريقة سير عمل الفريق الديناميكي، وتتقدم عبر المهام بطريقة مدروسة ومنهجية. يتبع تنفيذ المهام الترتيب المحدد مسبقًا في قائمة المهام، حيث يعمل ناتج مهمة واحدة كسياق للمهمة التالية. + +لتخصيص سياق المهمة، استخدم معامل `context` في فئة `Task` لتحديد المخرجات التي يجب استخدامها كسياق للمهام اللاحقة. + +## العملية الهرمية + +تحاكي التسلسل الهرمي المؤسسي، حيث يسمح CrewAI بتحديد وكيل مدير مخصص أو إنشاء واحد تلقائيًا، مما يتطلب تحديد نموذج لغة المدير (`manager_llm`). يشرف هذا الوكيل على تنفيذ المهام، بما في ذلك التخطيط والتفويض والتحقق. لا يتم تعيين المهام مسبقًا؛ يخصص المدير المهام للوكلاء بناءً على قدراتهم، ويراجع المخرجات، ويقيّم اكتمال المهام. + +## فئة Process: نظرة عامة مفصلة + +تم تنفيذ فئة `Process` كتعداد (`Enum`)، مما يضمن أمان الأنواع ويقيّد قيم العملية على الأنواع المحددة (`sequential`، `hierarchical`). العملية التوافقية مخطط لإدراجها مستقبلاً، مما يؤكد التزامنا بالتطوير والابتكار المستمر. + +## الخلاصة + +التعاون المنظم الذي تسهّله العمليات داخل CrewAI ضروري لتمكين العمل الجماعي المنهجي بين الوكلاء. +تم تحديث هذه الوثائق لتعكس أحدث الميزات والتحسينات والتكامل المخطط للعملية التوافقية، مما يضمن وصول المستخدمين إلى أحدث المعلومات وأكثرها شمولاً. diff --git a/docs/ar/concepts/production-architecture.mdx b/docs/ar/concepts/production-architecture.mdx new file mode 100644 index 000000000..19ba0cecb --- /dev/null +++ b/docs/ar/concepts/production-architecture.mdx @@ -0,0 +1,154 @@ +--- +title: بنية الإنتاج +description: أفضل الممارسات لبناء تطبيقات ذكاء اصطناعي جاهزة للإنتاج مع CrewAI +icon: server +mode: "wide" +--- + +# عقلية التدفق أولاً + +عند بناء تطبيقات ذكاء اصطناعي إنتاجية مع CrewAI، **نوصي بالبدء بتدفق (Flow)**. + +بينما يمكن تشغيل أطقم أو وكلاء فرديين، فإن تغليفهم في تدفق يوفر الهيكل اللازم لتطبيق متين وقابل للتوسع. + +## لماذا التدفقات؟ + +1. **إدارة الحالة**: توفر التدفقات طريقة مدمجة لإدارة الحالة عبر مراحل مختلفة من تطبيقك. هذا ضروري لتمرير البيانات بين الأطقم والحفاظ على السياق ومعالجة مدخلات المستخدم. +2. **التحكم**: تتيح لك التدفقات تحديد مسارات تنفيذ دقيقة، بما في ذلك الحلقات والشرطيات ومنطق التفريع. هذا أساسي لمعالجة الحالات الاستثنائية وضمان سلوك تطبيقك بشكل متوقع. +3. **المراقبة**: توفر التدفقات هيكلًا واضحًا يسهّل تتبع التنفيذ وتصحيح الأخطاء ومراقبة الأداء. نوصي باستخدام [تتبع CrewAI](/ar/observability/tracing) للحصول على رؤى تفصيلية. ما عليك سوى تشغيل `crewai login` لتفعيل ميزات المراقبة المجانية. + +## البنية + +يبدو تطبيق CrewAI الإنتاجي النموذجي هكذا: + +```mermaid +graph TD + Start((Start)) --> Flow[Flow Orchestrator] + Flow --> State{State Management} + State --> Step1[Step 1: Data Gathering] + Step1 --> Crew1[Research Crew] + Crew1 --> State + State --> Step2{Condition Check} + Step2 -- "Valid" --> Step3[Step 3: Execution] + Step3 --> Crew2[Action Crew] + Step2 -- "Invalid" --> End((End)) + Crew2 --> End +``` + +### 1. فئة التدفق +فئة `Flow` هي نقطة الدخول. تحدد مخطط الحالة والطرق التي تنفذ منطقك. + +```python +from crewai.flow.flow import Flow, listen, start +from pydantic import BaseModel + +class AppState(BaseModel): + user_input: str = "" + research_results: str = "" + final_report: str = "" + +class ProductionFlow(Flow[AppState]): + @start() + def gather_input(self): + # ... منطق الحصول على المدخلات ... + pass + + @listen(gather_input) + def run_research_crew(self): + # ... تشغيل طاقم ... + pass +``` + +### 2. إدارة الحالة +استخدم نماذج Pydantic لتعريف حالتك. يضمن هذا أمان الأنواع ويوضح البيانات المتاحة في كل مرحلة. + +- **اجعلها بسيطة**: خزّن فقط ما تحتاجه للاستمرار بين المراحل. +- **استخدم بيانات منظمة**: تجنب القواميس غير المنظمة قدر الإمكان. + +### 3. الأطقم كوحدات عمل +فوّض المهام المعقدة إلى الأطقم. يجب أن يكون الطاقم مركّزًا على هدف محدد (مثل "البحث في موضوع"، "كتابة مقال مدونة"). + +- **لا تبالغ في هندسة الأطقم**: اجعلها مركّزة. +- **مرر الحالة بشكل صريح**: مرر البيانات الضرورية من حالة التدفق إلى مدخلات الطاقم. + +```python + @listen(gather_input) + def run_research_crew(self): + crew = ResearchCrew() + result = crew.kickoff(inputs={"topic": self.state.user_input}) + self.state.research_results = result.raw +``` + +## عناصر التحكم الأولية + +استفد من عناصر التحكم الأولية في CrewAI لإضافة المتانة والتحكم إلى أطقمك. + +### 1. حواجز المهام +استخدم [حواجز المهام](/ar/concepts/tasks#task-guardrails) للتحقق من مخرجات المهام قبل قبولها. يضمن هذا أن وكلاءك ينتجون نتائج عالية الجودة. + +```python +def validate_content(result: TaskOutput) -> Tuple[bool, Any]: + if len(result.raw) < 100: + return (False, "Content is too short. Please expand.") + return (True, result.raw) + +task = Task( + ..., + guardrail=validate_content +) +``` + +### 2. المخرجات المنظمة +استخدم دائمًا المخرجات المنظمة (`output_pydantic` أو `output_json`) عند تمرير البيانات بين المهام أو إلى تطبيقك. يمنع هذا أخطاء التحليل ويضمن أمان الأنواع. + +```python +class ResearchResult(BaseModel): + summary: str + sources: List[str] + +task = Task( + ..., + output_pydantic=ResearchResult +) +``` + +### 3. خطافات LLM +استخدم [خطافات LLM](/ar/learn/llm-hooks) لفحص أو تعديل الرسائل قبل إرسالها إلى LLM، أو لتنقية الاستجابات. + +```python +@before_llm_call +def log_request(context): + print(f"Agent {context.agent.role} is calling the LLM...") +``` + +## أنماط النشر + +عند نشر تدفقك، ضع في اعتبارك ما يلي: + +### CrewAI Enterprise +أسهل طريقة لنشر تدفقك هي استخدام CrewAI Enterprise. تتعامل مع البنية التحتية والمصادقة والمراقبة نيابة عنك. + +راجع [دليل النشر](/ar/enterprise/guides/deploy-to-amp) للبدء. + +```bash +crewai deploy create +``` + +### التنفيذ غير المتزامن +للمهام طويلة التشغيل، استخدم `kickoff_async` لتجنب حظر واجهتك البرمجية. + +### الاستمرارية +استخدم مزيّن `@persist` لحفظ حالة تدفقك في قاعدة بيانات. يتيح لك هذا استئناف التنفيذ إذا تعطلت العملية أو إذا كنت بحاجة لانتظار مدخلات بشرية. + +```python +@persist +class ProductionFlow(Flow[AppState]): + # ... +``` + +## الخلاصة + +- **ابدأ بتدفق.** +- **حدد حالة واضحة.** +- **استخدم الأطقم للمهام المعقدة.** +- **انشر مع API واستمرارية.** diff --git a/docs/ar/concepts/reasoning.mdx b/docs/ar/concepts/reasoning.mdx new file mode 100644 index 000000000..33ec1d6e7 --- /dev/null +++ b/docs/ar/concepts/reasoning.mdx @@ -0,0 +1,148 @@ +--- +title: الاستدلال +description: "تعرّف على كيفية تفعيل واستخدام استدلال الوكيل لتحسين تنفيذ المهام." +icon: brain +mode: "wide" +--- + +## نظرة عامة + +استدلال الوكيل هو ميزة تتيح للوكلاء التأمل في المهمة وإنشاء خطة قبل التنفيذ. يساعد هذا الوكلاء على التعامل مع المهام بشكل أكثر منهجية ويضمن استعدادهم لأداء العمل المطلوب. + +## الاستخدام + +لتفعيل الاستدلال لوكيل، ما عليك سوى تعيين `reasoning=True` عند إنشاء الوكيل: + +```python +from crewai import Agent + +agent = Agent( + role="Data Analyst", + goal="Analyze complex datasets and provide insights", + backstory="You are an experienced data analyst with expertise in finding patterns in complex data.", + reasoning=True, # تفعيل الاستدلال + max_reasoning_attempts=3 # اختياري: تعيين حد أقصى لمحاولات الاستدلال +) +``` + +## كيف يعمل + +عند تفعيل الاستدلال، قبل تنفيذ المهمة، سيقوم الوكيل بما يلي: + +1. التأمل في المهمة وإنشاء خطة مفصلة +2. تقييم ما إذا كان مستعدًا لتنفيذ المهمة +3. تحسين الخطة حسب الحاجة حتى يصبح مستعدًا أو يصل إلى max_reasoning_attempts +4. حقن خطة الاستدلال في وصف المهمة قبل التنفيذ + +تساعد هذه العملية الوكيل على تقسيم المهام المعقدة إلى خطوات يمكن إدارتها وتحديد التحديات المحتملة قبل البدء. + +## خيارات التهيئة + + + تفعيل أو تعطيل الاستدلال + + + + الحد الأقصى لعدد المحاولات لتحسين الخطة قبل المتابعة بالتنفيذ. إذا كانت القيمة None (الافتراضي)، سيستمر الوكيل في التحسين حتى يصبح مستعدًا. + + +## مثال + +إليك مثالًا كاملًا: + +```python +from crewai import Agent, Task, Crew + +# إنشاء وكيل مع تفعيل الاستدلال +analyst = Agent( + role="Data Analyst", + goal="Analyze data and provide insights", + backstory="You are an expert data analyst.", + reasoning=True, + max_reasoning_attempts=3 # اختياري: تعيين حد لمحاولات الاستدلال +) + +# إنشاء مهمة +analysis_task = Task( + description="Analyze the provided sales data and identify key trends.", + expected_output="A report highlighting the top 3 sales trends.", + agent=analyst +) + +# إنشاء طاقم وتشغيل المهمة +crew = Crew(agents=[analyst], tasks=[analysis_task]) +result = crew.kickoff() + +print(result) +``` + +## معالجة الأخطاء + +صُممت عملية الاستدلال لتكون متينة، مع معالجة أخطاء مدمجة. إذا حدث خطأ أثناء الاستدلال، سيتابع الوكيل تنفيذ المهمة بدون خطة الاستدلال. يضمن هذا إمكانية تنفيذ المهام حتى في حالة فشل عملية الاستدلال. + +إليك كيفية التعامل مع الأخطاء المحتملة في الكود الخاص بك: + +```python +from crewai import Agent, Task +import logging + +# إعداد التسجيل لالتقاط أي أخطاء في الاستدلال +logging.basicConfig(level=logging.INFO) + +# إنشاء وكيل مع تفعيل الاستدلال +agent = Agent( + role="Data Analyst", + goal="Analyze data and provide insights", + reasoning=True, + max_reasoning_attempts=3 +) + +# إنشاء مهمة +task = Task( + description="Analyze the provided sales data and identify key trends.", + expected_output="A report highlighting the top 3 sales trends.", + agent=agent +) + +# تنفيذ المهمة +# إذا حدث خطأ أثناء الاستدلال، سيتم تسجيله وسيستمر التنفيذ +result = agent.execute_task(task) +``` + +## مثال على مخرجات الاستدلال + +إليك مثالًا على شكل خطة الاستدلال لمهمة تحليل البيانات: + +``` +Task: Analyze the provided sales data and identify key trends. + +Reasoning Plan: +I'll analyze the sales data to identify the top 3 trends. + +1. Understanding of the task: + I need to analyze sales data to identify key trends that would be valuable for business decision-making. + +2. Key steps I'll take: + - First, I'll examine the data structure to understand what fields are available + - Then I'll perform exploratory data analysis to identify patterns + - Next, I'll analyze sales by time periods to identify temporal trends + - I'll also analyze sales by product categories and customer segments + - Finally, I'll identify the top 3 most significant trends + +3. Approach to challenges: + - If the data has missing values, I'll decide whether to fill or filter them + - If the data has outliers, I'll investigate whether they're valid data points or errors + - If trends aren't immediately obvious, I'll apply statistical methods to uncover patterns + +4. Use of available tools: + - I'll use data analysis tools to explore and visualize the data + - I'll use statistical tools to identify significant patterns + - I'll use knowledge retrieval to access relevant information about sales analysis + +5. Expected outcome: + A concise report highlighting the top 3 sales trends with supporting evidence from the data. + +READY: I am ready to execute the task. +``` + +تساعد خطة الاستدلال هذه الوكيل على تنظيم نهجه تجاه المهمة، والنظر في التحديات المحتملة، وضمان تقديم المخرجات المتوقعة. diff --git a/docs/ar/concepts/skills.mdx b/docs/ar/concepts/skills.mdx new file mode 100644 index 000000000..89f29a90a --- /dev/null +++ b/docs/ar/concepts/skills.mdx @@ -0,0 +1,306 @@ +--- +title: المهارات +description: حزم المهارات المبنية على نظام الملفات التي تحقن خبرة المجال والتعليمات في إرشادات الوكلاء. +icon: bolt +mode: "wide" +--- + +## نظرة عامة + +المهارات هي مجلدات مستقلة توفر للوكلاء **تعليمات وإرشادات ومواد مرجعية خاصة بالمجال**. تُعرّف كل مهارة بملف `SKILL.md` يحتوي على بيانات وصفية YAML ومحتوى Markdown. + +عند التفعيل، يتم حقن تعليمات المهارة مباشرة في إرشادات مهمة الوكيل — مما يمنح الوكيل خبرة دون الحاجة لأي تغييرات في الكود. + + +**المهارات ليست أدوات.** هذه هي نقطة الارتباك الأكثر شيوعًا. + +- **المهارات** تحقن *تعليمات وسياق* في إرشادات الوكيل. تخبر الوكيل *كيف يفكر* في مشكلة ما. +- **الأدوات** تمنح الوكيل *دوال قابلة للاستدعاء* لاتخاذ إجراءات (البحث، قراءة الملفات، استدعاء APIs). + +غالبًا ما تحتاج **كليهما**: مهارات للخبرة، وأدوات للإجراء. يتم تكوينهما بشكل مستقل ويُكمّلان بعضهما. + + +--- + +## البداية السريعة + +### 1. إنشاء مجلد المهارة + +``` +skills/ +└── code-review/ + ├── SKILL.md # مطلوب — التعليمات + ├── references/ # اختياري — مستندات مرجعية + │ └── style-guide.md + └── scripts/ # اختياري — سكربتات قابلة للتنفيذ +``` + +### 2. كتابة SKILL.md الخاص بك + +```markdown +--- +name: code-review +description: Guidelines for conducting thorough code reviews with focus on security and performance. +metadata: + author: your-team + version: "1.0" +--- + +## إرشادات مراجعة الكود + +عند مراجعة الكود، اتبع قائمة التحقق هذه: + +1. **الأمان**: تحقق من ثغرات الحقن وتجاوز المصادقة وكشف البيانات +2. **الأداء**: ابحث عن استعلامات N+1 والتخصيصات غير الضرورية والاستدعاءات المحظورة +3. **القابلية للقراءة**: تأكد من وضوح التسمية والتعليقات المناسبة والأسلوب المتسق +4. **الاختبارات**: تحقق من تغطية اختبار كافية للوظائف الجديدة + +### مستويات الخطورة +- **حرج**: ثغرات أمنية، مخاطر فقدان البيانات → حظر الدمج +- **رئيسي**: مشاكل أداء، أخطاء منطقية → طلب تغييرات +- **ثانوي**: مسائل أسلوبية، اقتراحات تسمية → الموافقة مع تعليقات +``` + +### 3. ربطها بوكيل + +```python +from crewai import Agent +from crewai_tools import GithubSearchTool, FileReadTool + +reviewer = Agent( + role="Senior Code Reviewer", + goal="Review pull requests for quality and security issues", + backstory="Staff engineer with expertise in secure coding practices.", + skills=["./skills"], # يحقن إرشادات المراجعة + tools=[GithubSearchTool(), FileReadTool()], # يسمح للوكيل بقراءة الكود +) +``` + +الوكيل الآن لديه **خبرة** (من المهارة) و**قدرات** (من الأدوات) معًا. + +--- + +## المهارات + الأدوات: العمل معًا + +إليك أنماط شائعة توضح كيف تُكمّل المهارات والأدوات بعضهما: + +### النمط 1: مهارات فقط (خبرة المجال، بدون إجراءات مطلوبة) + +استخدم عندما يحتاج الوكيل لتعليمات محددة لكن لا يحتاج لاستدعاء خدمات خارجية: + +```python +agent = Agent( + role="Technical Writer", + goal="Write clear API documentation", + backstory="Expert technical writer", + skills=["./skills/api-docs-style"], # إرشادات وقوالب الكتابة + # لا حاجة لأدوات — الوكيل يكتب بناءً على السياق المقدم +) +``` + +### النمط 2: أدوات فقط (إجراءات، بدون خبرة خاصة) + +استخدم عندما يحتاج الوكيل لاتخاذ إجراءات لكن لا يحتاج لتعليمات مجال محددة: + +```python +from crewai_tools import SerperDevTool, ScrapeWebsiteTool + +agent = Agent( + role="Web Researcher", + goal="Find information about a topic", + backstory="Skilled at finding information online", + tools=[SerperDevTool(), ScrapeWebsiteTool()], # يمكنه البحث والاستخراج + # لا حاجة لمهارات — البحث العام لا يحتاج إرشادات خاصة +) +``` + +### النمط 3: مهارات + أدوات (خبرة وإجراءات) + +النمط الأكثر شيوعًا في العالم الحقيقي. المهارة توفر *كيف* تقترب من العمل؛ الأدوات توفر *ما* يمكن للوكيل فعله: + +```python +from crewai_tools import SerperDevTool, FileReadTool, CodeInterpreterTool + +analyst = Agent( + role="Security Analyst", + goal="Audit infrastructure for vulnerabilities", + backstory="Expert in cloud security and compliance", + skills=["./skills/security-audit"], # منهجية وقوائم تحقق التدقيق + tools=[ + SerperDevTool(), # البحث عن ثغرات معروفة + FileReadTool(), # قراءة ملفات التكوين + CodeInterpreterTool(), # تشغيل سكربتات التحليل + ], +) +``` + +### النمط 4: مهارات + MCP + +المهارات تعمل مع خوادم MCP بنفس الطريقة التي تعمل بها مع الأدوات: + +```python +agent = Agent( + role="Data Analyst", + goal="Analyze customer data and generate reports", + backstory="Expert data analyst with strong statistical background", + skills=["./skills/data-analysis"], # منهجية التحليل + mcps=["https://data-warehouse.example.com/sse"], # وصول بيانات عن بُعد +) +``` + +### النمط 5: مهارات + تطبيقات + +المهارات يمكن أن توجّه كيف يستخدم الوكيل تكاملات المنصة: + +```python +agent = Agent( + role="Customer Support Agent", + goal="Respond to customer inquiries professionally", + backstory="Experienced support representative", + skills=["./skills/support-playbook"], # قوالب الردود وقواعد التصعيد + apps=["gmail", "zendesk"], # يمكنه إرسال رسائل بريد وتحديث التذاكر +) +``` + +--- + +## المهارات على مستوى الطاقم + +يمكن تعيين المهارات على الطاقم لتُطبّق على **جميع الوكلاء**: + +```python +from crewai import Crew + +crew = Crew( + agents=[researcher, writer, reviewer], + tasks=[research_task, write_task, review_task], + skills=["./skills"], # جميع الوكلاء يحصلون على هذه المهارات +) +``` + +المهارات على مستوى الوكيل لها الأولوية — إذا تم اكتشاف نفس المهارة في كلا المستويين، يتم استخدام نسخة الوكيل. + +--- + +## تنسيق SKILL.md + +```markdown +--- +name: my-skill +description: وصف قصير لما تفعله هذه المهارة ومتى تُستخدم. +license: Apache-2.0 # اختياري +compatibility: crewai>=0.1.0 # اختياري +metadata: # اختياري + author: your-name + version: "1.0" +allowed-tools: web-search file-read # اختياري، تجريبي +--- + +التعليمات للوكيل تُكتب هنا. يتم حقن محتوى Markdown هذا +في إرشادات الوكيل عند تفعيل المهارة. +``` + +### حقول البيانات الوصفية + +| الحقل | مطلوب | الوصف | +| :-------------- | :------- | :----------------------------------------------------------------------- | +| `name` | نعم | 1-64 حرف. أحرف صغيرة أبجدية رقمية وشرطات. يجب أن يطابق اسم المجلد. | +| `description` | نعم | 1-1024 حرف. يصف ما تفعله المهارة ومتى تُستخدم. | +| `license` | لا | اسم الترخيص أو مرجع لملف ترخيص مضمّن. | +| `compatibility` | لا | حد أقصى 500 حرف. متطلبات البيئة (منتجات، حزم، شبكة). | +| `metadata` | لا | تعيين مفتاح-قيمة نصي عشوائي. | +| `allowed-tools` | لا | قائمة أدوات معتمدة مسبقًا مفصولة بمسافات. تجريبي. | + +--- + +## هيكل المجلد + +``` +my-skill/ +├── SKILL.md # مطلوب — البيانات الوصفية + التعليمات +├── scripts/ # اختياري — سكربتات قابلة للتنفيذ +├── references/ # اختياري — مستندات مرجعية +└── assets/ # اختياري — ملفات ثابتة (إعدادات، بيانات) +``` + +يجب أن يتطابق اسم المجلد مع حقل `name` في `SKILL.md`. مجلدات `scripts/` و `references/` و `assets/` متاحة في مسار المهارة `path` للوكلاء الذين يحتاجون للإشارة إلى الملفات مباشرة. + +--- + +## المهارات المحمّلة مسبقًا + +للمزيد من التحكم، يمكنك اكتشاف المهارات وتفعيلها برمجيًا: + +```python +from pathlib import Path +from crewai.skills import discover_skills, activate_skill + +# اكتشاف جميع المهارات في مجلد +skills = discover_skills(Path("./skills")) + +# تفعيلها (تحميل محتوى SKILL.md الكامل) +activated = [activate_skill(s) for s in skills] + +# تمرير إلى وكيل +agent = Agent( + role="Researcher", + goal="Find relevant information", + backstory="An expert researcher.", + skills=activated, +) +``` + +--- + +## كيف يتم تحميل المهارات + +تستخدم المهارات **الكشف التدريجي** — تحمّل فقط ما هو مطلوب في كل مرحلة: + +| المرحلة | ما يتم تحميله | متى | +| :--------- | :------------------------------------ | :------------------ | +| الاكتشاف | الاسم، الوصف، حقول البيانات الوصفية | `discover_skills()` | +| التفعيل | نص محتوى SKILL.md الكامل | `activate_skill()` | + +أثناء التنفيذ العادي للوكيل (تمرير مسارات المجلدات عبر `skills=["./skills"]`)، يتم اكتشاف المهارات وتفعيلها تلقائيًا. التحميل التدريجي مهم فقط عند استخدام الواجهة البرمجية. + +--- + +## المهارات مقابل المعرفة + +كلا المهارات والمعرفة تُعدّل إرشادات الوكيل، لكنهما يخدمان أغراضًا مختلفة: + +| الجانب | المهارات | المعرفة | +| :--- | :--- | :--- | +| **ما توفره** | تعليمات، إجراءات، إرشادات | حقائق، بيانات، معلومات | +| **كيف تُخزّن** | ملفات Markdown (SKILL.md) | مُضمّنة في مخزن متجهي (ChromaDB) | +| **كيف تُسترجع** | يتم حقن المحتوى الكامل في الإرشادات | البحث الدلالي يجد الأجزاء ذات الصلة | +| **الأفضل لـ** | المنهجيات، قوائم التحقق، أدلة الأسلوب | مستندات الشركة، معلومات المنتج، بيانات مرجعية | +| **يُعيّن عبر** | `skills=["./skills"]` | `knowledge_sources=[source]` | + +**القاعدة العامة:** إذا كان الوكيل يحتاج لاتباع *عملية*، استخدم مهارة. إذا كان يحتاج للرجوع إلى *بيانات*، استخدم المعرفة. + +--- + +## الأسئلة الشائعة + + + + يعتمد على حالة الاستخدام. المهارات والأدوات **مستقلتان** — يمكنك استخدام أيّ منهما أو كليهما أو لا شيء. + + - **مهارات فقط**: عندما يحتاج الوكيل خبرة لكن لا يحتاج إجراءات خارجية (مثال: الكتابة بإرشادات أسلوبية) + - **أدوات فقط**: عندما يحتاج الوكيل إجراءات لكن لا يحتاج منهجية خاصة (مثال: بحث بسيط على الويب) + - **كليهما**: عندما يحتاج الوكيل خبرة وإجراءات (مثال: تدقيق أمني بقوائم تحقق محددة وقدرة على فحص الكود) + + + + **لا.** حقل `allowed-tools` في SKILL.md هو بيانات وصفية تجريبية فقط — لا يُنشئ أو يحقن أي أدوات. يجب عليك دائمًا تعيين الأدوات بشكل منفصل عبر `tools=[]` أو `mcps=[]` أو `apps=[]`. + + + + المهارة على مستوى الوكيل لها الأولوية. يتم إزالة التكرار حسب الاسم — مهارات الوكيل تُعالج أولاً، لذا إذا ظهر نفس اسم المهارة في كلا المستويين، تُستخدم نسخة الوكيل. + + + + هناك تحذير ناعم عند 50,000 حرف، لكن بدون حد صارم. حافظ على تركيز المهارات وإيجازها للحصول على أفضل النتائج — الحقن الكبيرة في الإرشادات قد تُشتت انتباه الوكيل. + + diff --git a/docs/ar/concepts/tasks.mdx b/docs/ar/concepts/tasks.mdx new file mode 100644 index 000000000..bb239c5a5 --- /dev/null +++ b/docs/ar/concepts/tasks.mdx @@ -0,0 +1,1085 @@ +--- +title: المهام +description: دليل مفصل حول إدارة وإنشاء المهام ضمن إطار عمل CrewAI. +icon: list-check +mode: "wide" +--- + +## نظرة عامة + +في إطار عمل CrewAI، المهمة (`Task`) هي تكليف محدد يُنجزه وكيل (`Agent`). + +توفر المهام جميع التفاصيل اللازمة للتنفيذ، مثل الوصف والوكيل المسؤول والأدوات المطلوبة والمزيد، مما يسهّل مجموعة واسعة من تعقيدات الإجراءات. + +يمكن أن تكون المهام في CrewAI تعاونية، تتطلب عمل وكلاء متعددين معًا. تتم إدارة ذلك من خلال خصائص المهمة ويتم تنسيقه بواسطة عملية Crew، مما يعزز العمل الجماعي والكفاءة. + + +يتضمن CrewAI AMP منشئ مهام مرئي في Crew Studio يبسّط إنشاء المهام المعقدة وربطها. صمم تدفقات مهامك بصريًا واختبرها في الوقت الفعلي دون كتابة كود. + +![Task Builder Screenshot](/images/enterprise/crew-studio-interface.png) + +يتيح منشئ المهام المرئي: + +- إنشاء المهام بالسحب والإفلات +- تبعيات المهام المرئية والتدفق +- الاختبار والتحقق في الوقت الفعلي +- المشاركة والتعاون بسهولة + + +### تدفق تنفيذ المهام + +يمكن تنفيذ المهام بطريقتين: + +- **تسلسلي**: تُنفَّذ المهام بالترتيب الذي تم تعريفها به +- **هرمي**: تُعيَّن المهام للوكلاء بناءً على أدوارهم وخبراتهم + +يتم تحديد تدفق التنفيذ عند إنشاء الفريق: + +```python Code +crew = Crew( + agents=[agent1, agent2], + tasks=[task1, task2], + process=Process.sequential # or Process.hierarchical +) +``` + +## خصائص المهمة + +| الخاصية | المعاملات | النوع | الوصف | +| :------------------------------------- | :---------------------- | :-------------------------- | :-------------------------------------------------------------------------------------------------------------- | +| **الوصف** | `description` | `str` | بيان واضح وموجز لما تستلزمه المهمة. | +| **المخرجات المتوقعة** | `expected_output` | `str` | وصف مفصل لما يبدو عليه إتمام المهمة. | +| **الاسم** _(اختياري)_ | `name` | `Optional[str]` | معرّف اسمي للمهمة. | +| **الوكيل** _(اختياري)_ | `agent` | `Optional[BaseAgent]` | الوكيل المسؤول عن تنفيذ المهمة. | +| **الأدوات** _(اختياري)_ | `tools` | `List[BaseTool]` | الأدوات/الموارد التي يقتصر الوكيل على استخدامها لهذه المهمة. | +| **السياق** _(اختياري)_ | `context` | `Optional[List["Task"]]` | مهام أخرى ستُستخدم مخرجاتها كسياق لهذه المهمة. | +| **التنفيذ غير المتزامن** _(اختياري)_ | `async_execution` | `Optional[bool]` | ما إذا كان يجب تنفيذ المهمة بشكل غير متزامن. الافتراضي False. | +| **المدخلات البشرية** _(اختياري)_ | `human_input` | `Optional[bool]` | ما إذا كان يجب أن يراجع إنسان الإجابة النهائية للوكيل. الافتراضي False. | +| **Markdown** _(اختياري)_ | `markdown` | `Optional[bool]` | ما إذا كان يجب أن توجّه المهمة الوكيل لإعادة الإجابة النهائية بتنسيق Markdown. الافتراضي False. | +| **الإعداد** _(اختياري)_ | `config` | `Optional[Dict[str, Any]]` | معاملات إعداد خاصة بالمهمة. | +| **ملف المخرجات** _(اختياري)_ | `output_file` | `Optional[str]` | مسار الملف لتخزين مخرجات المهمة. | +| **إنشاء المجلد** _(اختياري)_ | `create_directory` | `Optional[bool]` | ما إذا كان يجب إنشاء المجلد لـ output_file إذا لم يكن موجودًا. الافتراضي True. | +| **مخرجات JSON** _(اختياري)_ | `output_json` | `Optional[Type[BaseModel]]` | نموذج Pydantic لهيكلة مخرجات JSON. | +| **مخرجات Pydantic** _(اختياري)_ | `output_pydantic` | `Optional[Type[BaseModel]]` | نموذج Pydantic لمخرجات المهمة. | +| **دالة الاسترجاع** _(اختياري)_ | `callback` | `Optional[Any]` | دالة/كائن يُنفَّذ بعد اكتمال المهمة. | +| **حارس** _(اختياري)_ | `guardrail` | `Optional[Callable]` | دالة للتحقق من مخرجات المهمة قبل الانتقال إلى المهمة التالية. | +| **حراس** _(اختياري)_ | `guardrails` | `Optional[List[Callable]]` | قائمة حراس للتحقق من مخرجات المهمة قبل الانتقال إلى المهمة التالية. | +| **أقصى محاولات الحارس** _(اختياري)_ | `guardrail_max_retries` | `Optional[int]` | الحد الأقصى لعدد المحاولات عند فشل التحقق من الحارس. الافتراضي 3. | + + + خاصية المهمة `max_retries` مهملة وستتم إزالتها في v1.0.0. + استخدم `guardrail_max_retries` بدلاً منها للتحكم في محاولات الإعادة عند فشل الحارس. + + +## إنشاء المهام + +هناك طريقتان لإنشاء المهام في CrewAI: باستخدام **إعداد YAML (موصى به)** أو تعريفها **مباشرة في الكود**. + +### إعداد YAML (موصى به) + +يوفر استخدام إعداد YAML طريقة أنظف وأكثر قابلية للصيانة لتعريف المهام. نوصي بشدة باستخدام هذا النهج لتعريف المهام في مشاريع CrewAI. + +بعد إنشاء مشروع CrewAI كما هو موضح في قسم [التثبيت](/ar/installation)، انتقل إلى ملف `src/latest_ai_development/config/tasks.yaml` وعدّل القالب ليتوافق مع متطلبات مهامك المحددة. + + +المتغيرات في ملفات YAML (مثل `{topic}`) سيتم استبدالها بالقيم من مدخلاتك عند تشغيل الفريق: +```python Code +crew.kickoff(inputs={'topic': 'AI Agents'}) +``` + + +إليك مثال على كيفية إعداد المهام باستخدام YAML: + +````yaml tasks.yaml +research_task: + description: > + Conduct a thorough research about {topic} + Make sure you find any interesting and relevant information given + the current year is 2025. + expected_output: > + A list with 10 bullet points of the most relevant information about {topic} + agent: researcher + +reporting_task: + description: > + Review the context you got and expand each topic into a full section for a report. + Make sure the report is detailed and contains any and all relevant information. + expected_output: > + A fully fledge reports with the mains topics, each with a full section of information. + Formatted as markdown without '```' + agent: reporting_analyst + markdown: true + output_file: report.md +```` + +لاستخدام إعداد YAML هذا في كودك، أنشئ فئة فريق ترث من `CrewBase`: + +```python crew.py +# src/latest_ai_development/crew.py + +from crewai import Agent, Crew, Process, Task +from crewai.project import CrewBase, agent, crew, task +from crewai_tools import SerperDevTool + +@CrewBase +class LatestAiDevelopmentCrew(): + """LatestAiDevelopment crew""" + + @agent + def researcher(self) -> Agent: + return Agent( + config=self.agents_config['researcher'], # type: ignore[index] + verbose=True, + tools=[SerperDevTool()] + ) + + @agent + def reporting_analyst(self) -> Agent: + return Agent( + config=self.agents_config['reporting_analyst'], # type: ignore[index] + verbose=True + ) + + @task + def research_task(self) -> Task: + return Task( + config=self.tasks_config['research_task'] # type: ignore[index] + ) + + @task + def reporting_task(self) -> Task: + return Task( + config=self.tasks_config['reporting_task'] # type: ignore[index] + ) + + @crew + def crew(self) -> Crew: + return Crew( + agents=[ + self.researcher(), + self.reporting_analyst() + ], + tasks=[ + self.research_task(), + self.reporting_task() + ], + process=Process.sequential + ) +``` + + + يجب أن تتطابق الأسماء المستخدمة في ملفات YAML (`agents.yaml` و `tasks.yaml`) + مع أسماء الدوال في كود Python الخاص بك. + + +### تعريف مباشر في الكود (بديل) + +بدلاً من ذلك، يمكنك تعريف المهام مباشرة في كودك دون استخدام إعداد YAML: + +```python task.py +from crewai import Task + +research_task = Task( + description=""" + Conduct a thorough research about AI Agents. + Make sure you find any interesting and relevant information given + the current year is 2025. + """, + expected_output=""" + A list with 10 bullet points of the most relevant information about AI Agents + """, + agent=researcher +) + +reporting_task = Task( + description=""" + Review the context you got and expand each topic into a full section for a report. + Make sure the report is detailed and contains any and all relevant information. + """, + expected_output=""" + A fully fledge reports with the mains topics, each with a full section of information. + """, + agent=reporting_analyst, + markdown=True, # Enable markdown formatting for the final output + output_file="report.md" +) +``` + + + حدد وكيلًا (`agent`) مباشرة للتعيين أو دع عملية CrewAI `hierarchical` + تقرر بناءً على الأدوار والتوفر وغيرها. + + +## مخرجات المهمة + +فهم مخرجات المهام أمر بالغ الأهمية لبناء سير عمل ذكاء اصطناعي فعال. يوفر CrewAI طريقة منظمة للتعامل مع نتائج المهام من خلال فئة `TaskOutput`، التي تدعم تنسيقات مخرجات متعددة ويمكن تمريرها بسهولة بين المهام. + +يتم تغليف مخرجات المهمة في إطار عمل CrewAI داخل فئة `TaskOutput`. توفر هذه الفئة طريقة منظمة للوصول إلى نتائج المهمة، بما في ذلك تنسيقات متنوعة مثل المخرجات الخام و JSON ونماذج Pydantic. + +بشكل افتراضي، سيتضمن `TaskOutput` المخرجات `raw` فقط. سيتضمن `TaskOutput` مخرجات `pydantic` أو `json_dict` فقط إذا تم إعداد كائن `Task` الأصلي مع `output_pydantic` أو `output_json` على التوالي. + +### خصائص مخرجات المهمة + +| الخاصية | المعاملات | النوع | الوصف | +| :---------------- | :-------------- | :------------------------- | :------------------------------------------------------------------------------------------------- | +| **الوصف** | `description` | `str` | وصف المهمة. | +| **الملخص** | `summary` | `Optional[str]` | ملخص المهمة، يُنشأ تلقائيًا من أول 10 كلمات من الوصف. | +| **الخام** | `raw` | `str` | المخرجات الخام للمهمة. هذا هو التنسيق الافتراضي للمخرجات. | +| **Pydantic** | `pydantic` | `Optional[BaseModel]` | كائن نموذج Pydantic يمثل المخرجات المنظمة للمهمة. | +| **قاموس JSON** | `json_dict` | `Optional[Dict[str, Any]]` | قاموس يمثل مخرجات JSON للمهمة. | +| **الوكيل** | `agent` | `str` | الوكيل الذي نفذ المهمة. | +| **تنسيق المخرجات**| `output_format` | `OutputFormat` | تنسيق مخرجات المهمة، مع خيارات تشمل RAW و JSON و Pydantic. الافتراضي هو RAW. | +| **الرسائل** | `messages` | `list[LLMMessage]` | الرسائل من آخر تنفيذ للمهمة. | + +### دوال وخصائص المهمة + +| الدالة/الخاصية | الوصف | +| :-------------- | :------------------------------------------------------------------------------------------------ | +| **json** | تُعيد تمثيل سلسلة JSON لمخرجات المهمة إذا كان تنسيق المخرجات JSON. | +| **to_dict** | تحوّل مخرجات JSON و Pydantic إلى قاموس. | +| **str** | تُعيد التمثيل النصي لمخرجات المهمة، مع أولوية Pydantic ثم JSON ثم الخام. | + +### الوصول إلى مخرجات المهمة + +بمجرد تنفيذ المهمة، يمكن الوصول إلى مخرجاتها من خلال خاصية `output` لكائن `Task`. توفر فئة `TaskOutput` طرقًا متنوعة للتفاعل مع هذه المخرجات وعرضها. + +#### مثال + +```python Code +# Example task +task = Task( + description='Find and summarize the latest AI news', + expected_output='A bullet list summary of the top 5 most important AI news', + agent=research_agent, + tools=[search_tool] +) + +# Execute the crew +crew = Crew( + agents=[research_agent], + tasks=[task], + verbose=True +) + +result = crew.kickoff() + +# Accessing the task output +task_output = task.output + +print(f"Task Description: {task_output.description}") +print(f"Task Summary: {task_output.summary}") +print(f"Raw Output: {task_output.raw}") +if task_output.json_dict: + print(f"JSON Output: {json.dumps(task_output.json_dict, indent=2)}") +if task_output.pydantic: + print(f"Pydantic Output: {task_output.pydantic}") +``` + +## تنسيق مخرجات Markdown + +يتيح معامل `markdown` تنسيق Markdown تلقائي لمخرجات المهام. عند تعيينه إلى `True`، ستوجّه المهمة الوكيل لتنسيق الإجابة النهائية باستخدام صيغة Markdown الصحيحة. + +### استخدام تنسيق Markdown + +```python Code +# Example task with markdown formatting enabled +formatted_task = Task( + description="Create a comprehensive report on AI trends", + expected_output="A well-structured report with headers, sections, and bullet points", + agent=reporter_agent, + markdown=True # Enable automatic markdown formatting +) +``` + +عند تعيين `markdown=True`، سيتلقى الوكيل تعليمات إضافية لتنسيق المخرجات باستخدام: + +- `#` للعناوين +- `**text**` للنص العريض +- `*text*` للنص المائل +- `-` أو `*` للقوائم النقطية +- `` `code` `` للكود المضمّن +- ` `language ``` لكتل الكود + +### إعداد YAML مع Markdown + +```yaml tasks.yaml +analysis_task: + description: > + Analyze the market data and create a detailed report + expected_output: > + A comprehensive analysis with charts and key findings + agent: analyst + markdown: true # Enable markdown formatting + output_file: analysis.md +``` + +### فوائد مخرجات Markdown + +- **تنسيق متسق**: يضمن اتباع جميع المخرجات لاتفاقيات Markdown الصحيحة +- **قابلية قراءة أفضل**: محتوى منظم مع عناوين وقوائم وتأكيد +- **جاهز للتوثيق**: يمكن استخدام المخرجات مباشرة في أنظمة التوثيق +- **توافق عبر المنصات**: Markdown مدعوم عالميًا + + + يتم إضافة تعليمات تنسيق Markdown تلقائيًا إلى موجّه المهمة + عند تعيين `markdown=True`، لذا لا تحتاج إلى تحديد متطلبات التنسيق + في وصف المهمة. + + +## تبعيات المهام والسياق + +يمكن للمهام الاعتماد على مخرجات مهام أخرى باستخدام خاصية `context`. على سبيل المثال: + +```python Code +research_task = Task( + description="Research the latest developments in AI", + expected_output="A list of recent AI developments", + agent=researcher +) + +analysis_task = Task( + description="Analyze the research findings and identify key trends", + expected_output="Analysis report of AI trends", + agent=analyst, + context=[research_task] # This task will wait for research_task to complete +) +``` + +## حراس المهام + +توفر حراس المهام طريقة للتحقق من مخرجات المهام وتحويلها قبل +تمريرها إلى المهمة التالية. تساعد هذه الميزة في ضمان جودة البيانات وتوفر +تغذية راجعة للوكلاء عندما لا تستوفي مخرجاتهم معايير محددة. + +يدعم CrewAI نوعين من الحراس: + +1. **حراس قائمون على الدوال**: دوال Python مع منطق تحقق مخصص، تمنحك تحكمًا كاملاً في عملية التحقق وتضمن نتائج موثوقة وحتمية. + +2. **حراس قائمون على LLM**: أوصاف نصية تستخدم LLM الخاص بالوكيل للتحقق من المخرجات بناءً على معايير لغة طبيعية. مثالية لمتطلبات التحقق المعقدة أو الذاتية. + +### الحراس القائمون على الدوال + +لإضافة حارس قائم على الدوال إلى مهمة، قدم دالة تحقق من خلال معامل `guardrail`: + +```python Code +from typing import Tuple, Union, Dict, Any +from crewai import TaskOutput + +def validate_blog_content(result: TaskOutput) -> Tuple[bool, Any]: + """Validate blog content meets requirements.""" + try: + # Check word count + word_count = len(result.raw.split()) + if word_count > 200: + return (False, "Blog content exceeds 200 words") + + # Additional validation logic here + return (True, result.raw.strip()) + except Exception as e: + return (False, "Unexpected error during validation") + +blog_task = Task( + description="Write a blog post about AI", + expected_output="A blog post under 200 words", + agent=blog_agent, + guardrail=validate_blog_content # Add the guardrail function +) +``` + +### الحراس القائمون على LLM (أوصاف نصية) + +بدلاً من كتابة دوال تحقق مخصصة، يمكنك استخدام أوصاف نصية تستفيد من التحقق القائم على LLM. عندما تقدم سلسلة نصية لمعامل `guardrail` أو `guardrails`، ينشئ CrewAI تلقائيًا `LLMGuardrail` يستخدم LLM الخاص بالوكيل للتحقق من المخرجات بناءً على وصفك. + +**المتطلبات**: + +- يجب أن يكون للمهمة وكيل (`agent`) مُعيّن (يستخدم الحارس LLM الخاص بالوكيل) +- قدم سلسلة نصية واضحة ووصفية تشرح معايير التحقق + +```python Code +from crewai import Task + +# Single LLM-based guardrail +blog_task = Task( + description="Write a blog post about AI", + expected_output="A blog post under 200 words", + agent=blog_agent, + guardrail="The blog post must be under 200 words and contain no technical jargon" +) +``` + +الحراس القائمون على LLM مفيدون بشكل خاص لـ: + +- **منطق التحقق المعقد** الذي يصعب التعبير عنه برمجيًا +- **المعايير الذاتية** مثل النبرة والأسلوب أو تقييمات الجودة +- **متطلبات اللغة الطبيعية** التي يسهل وصفها أكثر من برمجتها + +سيقوم حارس LLM بما يلي: + +1. تحليل مخرجات المهمة مقابل وصفك +2. إعادة `(True, output)` إذا امتثلت المخرجات للمعايير +3. إعادة `(False, feedback)` مع تغذية راجعة محددة إذا فشل التحقق + +**مثال مع معايير تحقق مفصلة**: + +```python Code +research_task = Task( + description="Research the latest developments in quantum computing", + expected_output="A comprehensive research report", + agent=researcher_agent, + guardrail=""" + The research report must: + - Be at least 1000 words long + - Include at least 5 credible sources + - Cover both technical and practical applications + - Be written in a professional, academic tone + - Avoid speculation or unverified claims + """ +) +``` + +### حراس متعددون + +يمكنك تطبيق حراس متعددين على مهمة باستخدام معامل `guardrails`. تُنفَّذ الحراس المتعددون بالتسلسل، حيث يتلقى كل حارس المخرجات من السابق. يتيح لك هذا سلسلة خطوات التحقق والتحويل. + +يقبل معامل `guardrails`: + +- قائمة من دوال الحراس أو أوصاف نصية +- حارس واحد (دالة أو سلسلة نصية) (مثل `guardrail`) + +**ملاحظة**: إذا تم تقديم `guardrails`، فإنه يأخذ الأولوية على `guardrail`. سيتم تجاهل معامل `guardrail` عند تعيين `guardrails`. + +```python Code +from typing import Tuple, Any +from crewai import TaskOutput, Task + +def validate_word_count(result: TaskOutput) -> Tuple[bool, Any]: + """Validate word count is within limits.""" + word_count = len(result.raw.split()) + if word_count < 100: + return (False, f"Content too short: {word_count} words. Need at least 100 words.") + if word_count > 500: + return (False, f"Content too long: {word_count} words. Maximum is 500 words.") + return (True, result.raw) + +def validate_no_profanity(result: TaskOutput) -> Tuple[bool, Any]: + """Check for inappropriate language.""" + profanity_words = ["badword1", "badword2"] # Example list + content_lower = result.raw.lower() + for word in profanity_words: + if word in content_lower: + return (False, f"Inappropriate language detected: {word}") + return (True, result.raw) + +def format_output(result: TaskOutput) -> Tuple[bool, Any]: + """Format and clean the output.""" + formatted = result.raw.strip() + # Capitalize first letter + formatted = formatted[0].upper() + formatted[1:] if formatted else formatted + return (True, formatted) + +# Apply multiple guardrails sequentially +blog_task = Task( + description="Write a blog post about AI", + expected_output="A well-formatted blog post between 100-500 words", + agent=blog_agent, + guardrails=[ + validate_word_count, # First: validate length + validate_no_profanity, # Second: check content + format_output # Third: format the result + ], + guardrail_max_retries=3 +) +``` + +في هذا المثال، تُنفَّذ الحراس بالترتيب: + +1. `validate_word_count` يتحقق من عدد الكلمات +2. `validate_no_profanity` يتحقق من اللغة غير الملائمة (باستخدام المخرجات من الخطوة 1) +3. `format_output` ينسّق النتيجة النهائية (باستخدام المخرجات من الخطوة 2) + +إذا فشل أي حارس، يتم إرسال الخطأ إلى الوكيل، وتُعاد المهمة حتى `guardrail_max_retries` مرة. + +**مزج الحراس القائمين على الدوال و LLM**: + +يمكنك الجمع بين الحراس القائمين على الدوال والنصية في نفس القائمة: + +```python Code +from typing import Tuple, Any +from crewai import TaskOutput, Task + +def validate_word_count(result: TaskOutput) -> Tuple[bool, Any]: + """Validate word count is within limits.""" + word_count = len(result.raw.split()) + if word_count < 100: + return (False, f"Content too short: {word_count} words. Need at least 100 words.") + if word_count > 500: + return (False, f"Content too long: {word_count} words. Maximum is 500 words.") + return (True, result.raw) + +# Mix function-based and LLM-based guardrails +blog_task = Task( + description="Write a blog post about AI", + expected_output="A well-formatted blog post between 100-500 words", + agent=blog_agent, + guardrails=[ + validate_word_count, # Function-based: precise word count check + "The content must be engaging and suitable for a general audience", # LLM-based: subjective quality check + "The writing style should be clear, concise, and free of technical jargon" # LLM-based: style validation + ], + guardrail_max_retries=3 +) +``` + +يجمع هذا النهج بين دقة التحقق البرمجي ومرونة التقييم القائم على LLM للمعايير الذاتية. + +### متطلبات دالة الحارس + +1. **توقيع الدالة**: + + - يجب أن تقبل معاملًا واحدًا بالضبط (مخرجات المهمة) + - يجب أن تُعيد tuple من `(bool, Any)` + - يُوصى بتلميحات الأنواع لكنها اختيارية + +2. **قيم الإعادة**: + - عند النجاح: تُعيد tuple من `(bool, Any)`. مثال: `(True, validated_result)` + - عند الفشل: تُعيد tuple من `(bool, str)`. مثال: `(False, "Error message explain the failure")` + +### أفضل ممارسات معالجة الأخطاء + +1. **استجابات أخطاء منظمة**: + +```python Code +from crewai import TaskOutput, LLMGuardrail + +def validate_with_context(result: TaskOutput) -> Tuple[bool, Any]: + try: + # Main validation logic + validated_data = perform_validation(result) + return (True, validated_data) + except ValidationError as e: + return (False, f"VALIDATION_ERROR: {str(e)}") + except Exception as e: + return (False, str(e)) +``` + +2. **فئات الأخطاء**: + + - استخدم رموز خطأ محددة + - ضمّن السياق ذا الصلة + - قدم تغذية راجعة قابلة للتنفيذ + +3. **سلسلة التحقق**: + +```python Code +from typing import Any, Dict, List, Tuple, Union +from crewai import TaskOutput + +def complex_validation(result: TaskOutput) -> Tuple[bool, Any]: + """Chain multiple validation steps.""" + # Step 1: Basic validation + if not result: + return (False, "Empty result") + + # Step 2: Content validation + try: + validated = validate_content(result) + if not validated: + return (False, "Invalid content") + + # Step 3: Format validation + formatted = format_output(validated) + return (True, formatted) + except Exception as e: + return (False, str(e)) +``` + +### التعامل مع نتائج الحارس + +عندما يُعيد حارس `(False, error)`: + +1. يتم إرسال الخطأ إلى الوكيل +2. يحاول الوكيل إصلاح المشكلة +3. تتكرر العملية حتى: + - يُعيد الحارس `(True, result)` + - يتم الوصول إلى الحد الأقصى للمحاولات (`guardrail_max_retries`) + +مثال مع معالجة إعادة المحاولة: + +```python Code +from typing import Optional, Tuple, Union +from crewai import TaskOutput, Task + +def validate_json_output(result: TaskOutput) -> Tuple[bool, Any]: + """Validate and parse JSON output.""" + try: + # Try to parse as JSON + data = json.loads(result) + return (True, data) + except json.JSONDecodeError as e: + return (False, "Invalid JSON format") + +task = Task( + description="Generate a JSON report", + expected_output="A valid JSON object", + agent=analyst, + guardrail=validate_json_output, + guardrail_max_retries=3 # Limit retry attempts +) +``` + +## الحصول على مخرجات منظمة ومتسقة من المهام + + + من المهم أيضًا ملاحظة أن مخرجات المهمة الأخيرة في الفريق + تصبح المخرجات النهائية للفريق نفسه. + + +### استخدام `output_pydantic` + +تتيح لك خاصية `output_pydantic` تحديد نموذج Pydantic يجب أن تتوافق معه مخرجات المهمة. هذا يضمن أن المخرجات ليست منظمة فحسب، بل تم التحقق منها وفقًا لنموذج Pydantic. + +إليك مثال يوضح كيفية استخدام output_pydantic: + +```python Code +import json + +from crewai import Agent, Crew, Process, Task +from pydantic import BaseModel + + +class Blog(BaseModel): + title: str + content: str + + +blog_agent = Agent( + role="Blog Content Generator Agent", + goal="Generate a blog title and content", + backstory="""You are an expert content creator, skilled in crafting engaging and informative blog posts.""", + verbose=False, + allow_delegation=False, + llm="gpt-4o", +) + +task1 = Task( + description="""Create a blog title and content on a given topic. Make sure the content is under 200 words.""", + expected_output="A compelling blog title and well-written content.", + agent=blog_agent, + output_pydantic=Blog, +) + +# Instantiate your crew with a sequential process +crew = Crew( + agents=[blog_agent], + tasks=[task1], + verbose=True, + process=Process.sequential, +) + +result = crew.kickoff() + +# Option 1: Accessing Properties Using Dictionary-Style Indexing +print("Accessing Properties - Option 1") +title = result["title"] +content = result["content"] +print("Title:", title) +print("Content:", content) + +# Option 2: Accessing Properties Directly from the Pydantic Model +print("Accessing Properties - Option 2") +title = result.pydantic.title +content = result.pydantic.content +print("Title:", title) +print("Content:", content) + +# Option 3: Accessing Properties Using the to_dict() Method +print("Accessing Properties - Option 3") +output_dict = result.to_dict() +title = output_dict["title"] +content = output_dict["content"] +print("Title:", title) +print("Content:", content) + +# Option 4: Printing the Entire Blog Object +print("Accessing Properties - Option 5") +print("Blog:", result) + +``` + +في هذا المثال: + +- يتم تعريف نموذج Pydantic Blog مع حقلي title و content. +- تستخدم المهمة task1 خاصية output_pydantic لتحديد أن مخرجاتها يجب أن تتوافق مع نموذج Blog. +- بعد تنفيذ الفريق، يمكنك الوصول إلى المخرجات المنظمة بعدة طرق كما هو موضح. + +#### شرح الوصول إلى المخرجات + +1. الفهرسة بأسلوب القاموس: يمكنك الوصول مباشرة إلى الحقول باستخدام result["field_name"]. يعمل هذا لأن فئة CrewOutput تنفذ دالة **getitem**. +2. مباشرة من نموذج Pydantic: الوصول إلى الخصائص مباشرة من كائن result.pydantic. +3. باستخدام دالة to_dict(): تحويل المخرجات إلى قاموس والوصول إلى الحقول. +4. طباعة الكائن بالكامل: ببساطة اطبع كائن result لرؤية المخرجات المنظمة. + +### استخدام `output_json` + +تتيح لك خاصية `output_json` تحديد المخرجات المتوقعة بتنسيق JSON. هذا يضمن أن مخرجات المهمة هي هيكل JSON صالح يمكن تحليله واستخدامه بسهولة في تطبيقك. + +إليك مثال يوضح كيفية استخدام `output_json`: + +```python Code +import json + +from crewai import Agent, Crew, Process, Task +from pydantic import BaseModel + + +# Define the Pydantic model for the blog +class Blog(BaseModel): + title: str + content: str + + +# Define the agent +blog_agent = Agent( + role="Blog Content Generator Agent", + goal="Generate a blog title and content", + backstory="""You are an expert content creator, skilled in crafting engaging and informative blog posts.""", + verbose=False, + allow_delegation=False, + llm="gpt-4o", +) + +# Define the task with output_json set to the Blog model +task1 = Task( + description="""Create a blog title and content on a given topic. Make sure the content is under 200 words.""", + expected_output="A JSON object with 'title' and 'content' fields.", + agent=blog_agent, + output_json=Blog, +) + +# Instantiate the crew with a sequential process +crew = Crew( + agents=[blog_agent], + tasks=[task1], + verbose=True, + process=Process.sequential, +) + +# Kickoff the crew to execute the task +result = crew.kickoff() + +# Option 1: Accessing Properties Using Dictionary-Style Indexing +print("Accessing Properties - Option 1") +title = result["title"] +content = result["content"] +print("Title:", title) +print("Content:", content) + +# Option 2: Printing the Entire Blog Object +print("Accessing Properties - Option 2") +print("Blog:", result) +``` + +في هذا المثال: + +- يتم تعريف نموذج Pydantic Blog مع حقلي title و content، الذي يُستخدم لتحديد هيكل مخرجات JSON. +- تستخدم المهمة task1 خاصية output_json للإشارة إلى أنها تتوقع مخرجات JSON متوافقة مع نموذج Blog. +- بعد تنفيذ الفريق، يمكنك الوصول إلى مخرجات JSON المنظمة بطريقتين كما هو موضح. + +#### شرح الوصول إلى المخرجات + +1. الوصول إلى الخصائص باستخدام الفهرسة بأسلوب القاموس: يمكنك الوصول إلى الحقول مباشرة باستخدام result["field_name"]. هذا ممكن لأن فئة CrewOutput تنفذ دالة **getitem**، مما يتيح لك معاملة المخرجات كقاموس. في هذا الخيار، نسترد title و content من النتيجة. +2. طباعة كائن Blog بالكامل: بطباعة result، تحصل على التمثيل النصي لكائن CrewOutput. نظرًا لأن دالة **str** منفذة لإعادة مخرجات JSON، سيعرض هذا المخرجات الكاملة كسلسلة منسقة تمثل كائن Blog. + +--- + +باستخدام output_pydantic أو output_json، تضمن أن مهامك تنتج مخرجات بتنسيق متسق ومنظم، مما يسهّل معالجة البيانات واستخدامها داخل تطبيقك أو عبر مهام متعددة. + +## دمج الأدوات مع المهام + +استفد من أدوات [CrewAI Toolkit](https://github.com/joaomdmoura/crewai-tools) و [LangChain Tools](https://python.langchain.com/docs/integrations/tools) لتحسين أداء المهام وتفاعل الوكلاء. + +## إنشاء مهمة بأدوات + +```python Code +import os +os.environ["OPENAI_API_KEY"] = "Your Key" +os.environ["SERPER_API_KEY"] = "Your Key" # serper.dev API key + +from crewai import Agent, Task, Crew +from crewai_tools import SerperDevTool + +research_agent = Agent( + role='Researcher', + goal='Find and summarize the latest AI news', + backstory="""You're a researcher at a large company. + You're responsible for analyzing data and providing insights + to the business.""", + verbose=True +) + +# to perform a semantic search for a specified query from a text's content across the internet +search_tool = SerperDevTool() + +task = Task( + description='Find and summarize the latest AI news', + expected_output='A bullet list summary of the top 5 most important AI news', + agent=research_agent, + tools=[search_tool] +) + +crew = Crew( + agents=[research_agent], + tasks=[task], + verbose=True +) + +result = crew.kickoff() +print(result) +``` + +يوضح هذا كيف يمكن للمهام ذات الأدوات المحددة تجاوز المجموعة الافتراضية للوكيل لتنفيذ مهام مخصصة. + +## الإشارة إلى مهام أخرى + +في CrewAI، يتم تمرير مخرجات مهمة واحدة تلقائيًا إلى المهمة التالية، لكن يمكنك تحديد مخرجات مهام بعينها، بما في ذلك عدة مهام، لاستخدامها كسياق لمهمة أخرى. + +هذا مفيد عندما تكون لديك مهمة تعتمد على مخرجات مهمة أخرى لا يتم تنفيذها مباشرة بعدها. يتم ذلك من خلال خاصية `context` للمهمة: + +```python Code +# ... + +research_ai_task = Task( + description="Research the latest developments in AI", + expected_output="A list of recent AI developments", + async_execution=True, + agent=research_agent, + tools=[search_tool] +) + +research_ops_task = Task( + description="Research the latest developments in AI Ops", + expected_output="A list of recent AI Ops developments", + async_execution=True, + agent=research_agent, + tools=[search_tool] +) + +write_blog_task = Task( + description="Write a full blog post about the importance of AI and its latest news", + expected_output="Full blog post that is 4 paragraphs long", + agent=writer_agent, + context=[research_ai_task, research_ops_task] +) + +#... +``` + +## التنفيذ غير المتزامن + +يمكنك تعريف مهمة ليتم تنفيذها بشكل غير متزامن. هذا يعني أن الفريق لن ينتظر اكتمالها للمتابعة مع المهمة التالية. هذا مفيد للمهام التي تستغرق وقتًا طويلاً، أو التي ليست حاسمة لتنفيذ المهام التالية. + +يمكنك بعد ذلك استخدام خاصية `context` لتحديد في مهمة مستقبلية أنها يجب أن تنتظر اكتمال مخرجات المهمة غير المتزامنة. + +```python Code +#... + +list_ideas = Task( + description="List of 5 interesting ideas to explore for an article about AI.", + expected_output="Bullet point list of 5 ideas for an article.", + agent=researcher, + async_execution=True # Will be executed asynchronously +) + +list_important_history = Task( + description="Research the history of AI and give me the 5 most important events.", + expected_output="Bullet point list of 5 important events.", + agent=researcher, + async_execution=True # Will be executed asynchronously +) + +write_article = Task( + description="Write an article about AI, its history, and interesting ideas.", + expected_output="A 4 paragraph article about AI.", + agent=writer, + context=[list_ideas, list_important_history] # Will wait for the output of the two tasks to be completed +) + +#... +``` + +## آلية دالة الاسترجاع + +يتم تنفيذ دالة الاسترجاع بعد اكتمال المهمة، مما يتيح تشغيل إجراءات أو إشعارات بناءً على نتيجة المهمة. + +```python Code +# ... + +def callback_function(output: TaskOutput): + # Do something after the task is completed + # Example: Send an email to the manager + print(f""" + Task completed! + Task: {output.description} + Output: {output.raw} + """) + +research_task = Task( + description='Find and summarize the latest AI news', + expected_output='A bullet list summary of the top 5 most important AI news', + agent=research_agent, + tools=[search_tool], + callback=callback_function +) + +#... +``` + +## الوصول إلى مخرجات مهمة محددة + +بمجرد انتهاء الفريق من التشغيل، يمكنك الوصول إلى مخرجات مهمة محددة باستخدام خاصية `output` لكائن المهمة: + +```python Code +# ... +task1 = Task( + description='Find and summarize the latest AI news', + expected_output='A bullet list summary of the top 5 most important AI news', + agent=research_agent, + tools=[search_tool] +) + +#... + +crew = Crew( + agents=[research_agent], + tasks=[task1, task2, task3], + verbose=True +) + +result = crew.kickoff() + +# Returns a TaskOutput object with the description and results of the task +print(f""" + Task completed! + Task: {task1.output.description} + Output: {task1.output.raw} +""") +``` + +## آلية تجاوز الأدوات + +تحديد الأدوات في مهمة يتيح التكيف الديناميكي لقدرات الوكيل، مما يؤكد مرونة CrewAI. + +## آليات معالجة الأخطاء والتحقق + +أثناء إنشاء المهام وتنفيذها، توجد آليات تحقق معينة لضمان متانة وموثوقية خصائص المهمة. تشمل على سبيل المثال لا الحصر: + +- ضمان تعيين نوع مخرجات واحد فقط لكل مهمة للحفاظ على توقعات مخرجات واضحة. +- منع التعيين اليدوي لخاصية `id` للحفاظ على سلامة نظام المعرّفات الفريدة. + +تساعد عمليات التحقق هذه في الحفاظ على اتساق وموثوقية تنفيذ المهام ضمن إطار عمل crewAI. + +## إنشاء المجلدات عند حفظ الملفات + +يتحكم معامل `create_directory` فيما إذا كان يجب على CrewAI إنشاء المجلدات تلقائيًا عند حفظ مخرجات المهام في ملفات. هذه الميزة مفيدة بشكل خاص لتنظيم المخرجات وضمان هيكلة مسارات الملفات بشكل صحيح، خاصة عند العمل مع تسلسلات مشاريع معقدة. + +### السلوك الافتراضي + +بشكل افتراضي، `create_directory=True`، مما يعني أن CrewAI سينشئ تلقائيًا أي مجلدات مفقودة في مسار ملف المخرجات: + +```python Code +# Default behavior - directories are created automatically +report_task = Task( + description='Generate a comprehensive market analysis report', + expected_output='A detailed market analysis with charts and insights', + agent=analyst_agent, + output_file='reports/2025/market_analysis.md', # Creates 'reports/2025/' if it doesn't exist + markdown=True +) +``` + +### تعطيل إنشاء المجلدات + +إذا كنت تريد منع الإنشاء التلقائي للمجلدات والتأكد من وجود المجلد مسبقًا، عيّن `create_directory=False`: + +```python Code +# Strict mode - directory must already exist +strict_output_task = Task( + description='Save critical data that requires existing infrastructure', + expected_output='Data saved to pre-configured location', + agent=data_agent, + output_file='secure/vault/critical_data.json', + create_directory=False # Will raise RuntimeError if 'secure/vault/' doesn't exist +) +``` + +### إعداد YAML + +يمكنك أيضًا إعداد هذا السلوك في تعريفات مهام YAML: + +```yaml tasks.yaml +analysis_task: + description: > + Generate quarterly financial analysis + expected_output: > + A comprehensive financial report with quarterly insights + agent: financial_analyst + output_file: reports/quarterly/q4_2024_analysis.pdf + create_directory: true # Automatically create 'reports/quarterly/' directory + +audit_task: + description: > + Perform compliance audit and save to existing audit directory + expected_output: > + A compliance audit report + agent: auditor + output_file: audit/compliance_report.md + create_directory: false # Directory must already exist +``` + +### حالات الاستخدام + +**إنشاء المجلدات تلقائيًا (`create_directory=True`):** + +- بيئات التطوير والنماذج الأولية +- إنشاء تقارير ديناميكية مع مجلدات قائمة على التاريخ +- سير عمل آلي حيث قد يختلف هيكل المجلدات +- تطبيقات متعددة المستأجرين مع مجلدات خاصة بالمستخدمين + +**إدارة المجلدات يدويًا (`create_directory=False`):** + +- بيئات الإنتاج مع ضوابط نظام ملفات صارمة +- التطبيقات الحساسة أمنيًا حيث يجب إعداد المجلدات مسبقًا +- الأنظمة ذات متطلبات أذونات محددة +- بيئات الامتثال حيث يتم مراقبة إنشاء المجلدات + +### معالجة الأخطاء + +عندما يكون `create_directory=False` والمجلد غير موجود، سيرفع CrewAI خطأ `RuntimeError`: + +```python Code +try: + result = crew.kickoff() +except RuntimeError as e: + # Handle missing directory error + print(f"Directory creation failed: {e}") + # Create directory manually or use fallback location +``` + +شاهد الفيديو أدناه لمعرفة كيفية استخدام المخرجات المنظمة في CrewAI: + + + +## الخلاصة + +المهام هي القوة الدافعة وراء إجراءات الوكلاء في CrewAI. +من خلال تعريف المهام ونتائجها بشكل صحيح، تمهّد الطريق لعمل وكلاء الذكاء الاصطناعي بفعالية، سواء بشكل مستقل أو كوحدة تعاونية. +تجهيز المهام بالأدوات المناسبة وفهم عملية التنفيذ واتباع ممارسات التحقق المتينة أمور حاسمة لتعظيم إمكانات CrewAI، +وضمان إعداد الوكلاء بفعالية لتكليفاتهم وتنفيذ المهام كما هو مقصود. diff --git a/docs/ar/concepts/testing.mdx b/docs/ar/concepts/testing.mdx new file mode 100644 index 000000000..061dc7fb3 --- /dev/null +++ b/docs/ar/concepts/testing.mdx @@ -0,0 +1,49 @@ +--- +title: الاختبار +description: تعرّف على كيفية اختبار طاقم CrewAI وتقييم أدائه. +icon: vial +mode: "wide" +--- + +## نظرة عامة + +يُعد الاختبار جزءًا حيويًا من عملية التطوير، ومن الضروري التأكد من أن طاقمك يعمل كما هو متوقع. مع CrewAI، يمكنك اختبار طاقمك وتقييم أدائه بسهولة باستخدام إمكانيات الاختبار المدمجة. + +### استخدام ميزة الاختبار + +أضفنا أمر CLI `crewai test` لتسهيل اختبار طاقمك. سيقوم هذا الأمر بتشغيل طاقمك لعدد محدد من التكرارات وتوفير مقاييس أداء مفصلة. المعاملات هي `n_iterations` و `model`، وهي اختيارية وتكون قيمها الافتراضية 2 و `gpt-4o-mini` على التوالي. حاليًا، المزود الوحيد المتاح هو OpenAI. + +```bash +crewai test +``` + +إذا أردت تشغيل المزيد من التكرارات أو استخدام نموذج مختلف، يمكنك تحديد المعاملات هكذا: + +```bash +crewai test --n_iterations 5 --model gpt-4o +``` + +أو باستخدام الصيغة المختصرة: + +```bash +crewai test -n 5 -m gpt-4o +``` + +عند تشغيل أمر `crewai test`، سيتم تنفيذ الطاقم للعدد المحدد من التكرارات، وستُعرض مقاييس الأداء في نهاية التشغيل. + +سيظهر جدول الدرجات في النهاية لعرض أداء الطاقم من حيث المقاييس التالية: + +
**درجات المهام (1-10 الأعلى أفضل)**
+ +| المهام/الطاقم/الوكلاء | التشغيل 1 | التشغيل 2 | المجموع المتوسط | الوكلاء | معلومات إضافية | +|:------------------|:-----:|:-----:|:----------:|:------------------------------:|:---------------------------------| +| المهمة 1 | 9.0 | 9.5 | **9.2** | Professional Insights | | +| | | | | Researcher | | +| المهمة 2 | 9.0 | 10.0 | **9.5** | Company Profile Investigator | | +| المهمة 3 | 9.0 | 9.0 | **9.0** | Automation Insights | | +| | | | | Specialist | | +| المهمة 4 | 9.0 | 9.0 | **9.0** | Final Report Compiler | Automation Insights Specialist | +| الطاقم | 9.00 | 9.38 | **9.2** | | | +| زمن التنفيذ (ثانية) | 126 | 145 | **135** | | | + +يوضح المثال أعلاه نتائج الاختبار لتشغيلين للطاقم مع مهمتين، مع الدرجة الإجمالية المتوسطة لكل مهمة والطاقم ككل. diff --git a/docs/ar/concepts/tools.mdx b/docs/ar/concepts/tools.mdx new file mode 100644 index 000000000..8b1e07aa1 --- /dev/null +++ b/docs/ar/concepts/tools.mdx @@ -0,0 +1,290 @@ +--- +title: الأدوات +description: فهم واستخدام الأدوات ضمن إطار عمل CrewAI لتعاون الوكلاء وتنفيذ المهام. +icon: screwdriver-wrench +mode: "wide" +--- + +## نظرة عامة + +تُمكّن أدوات CrewAI الوكلاء بقدرات تتراوح من البحث على الويب وتحليل البيانات إلى التعاون وتفويض المهام بين الزملاء. +توضح هذه الوثائق كيفية إنشاء هذه الأدوات ودمجها والاستفادة منها ضمن إطار عمل CrewAI، بما في ذلك التركيز على أدوات التعاون. + + + الأدوات تمنح الوكلاء **دوال قابلة للاستدعاء** لاتخاذ إجراءات. تعمل جنبًا إلى جنب مع [MCP](/ar/mcp/overview) (خوادم أدوات عن بُعد) و[التطبيقات](/ar/concepts/agent-capabilities) (تكاملات المنصة) و[المهارات](/ar/concepts/skills) (خبرة المجال) و[المعرفة](/ar/concepts/knowledge) (حقائق مُسترجعة). راجع نظرة عامة على [قدرات الوكيل](/ar/concepts/agent-capabilities) لفهم متى تستخدم كل نوع. + + +## ما هي الأداة؟ + +الأداة في CrewAI هي مهارة أو وظيفة يمكن للوكلاء استخدامها لأداء إجراءات مختلفة. +يشمل ذلك أدوات من [مجموعة أدوات CrewAI](https://github.com/joaomdmoura/crewai-tools) و[أدوات LangChain](https://python.langchain.com/docs/integrations/tools)، +مما يُمكّن كل شيء من عمليات البحث البسيطة إلى التفاعلات المعقدة والعمل الجماعي الفعال بين الوكلاء. + + +يوفر CrewAI AMP مستودع أدوات شامل مع تكاملات جاهزة لأنظمة الأعمال الشائعة وواجهات API. انشر الوكلاء مع أدوات المؤسسة في دقائق بدلاً من أيام. + +يتضمن مستودع أدوات المؤسسة: + +- موصلات جاهزة لأنظمة المؤسسة الشائعة +- واجهة إنشاء أدوات مخصصة +- إمكانيات التحكم في الإصدارات والمشاركة +- ميزات الأمان والامتثال + + +## الخصائص الرئيسية للأدوات + +- **المنفعة**: مصممة لمهام مثل البحث على الويب وتحليل البيانات وإنشاء المحتوى وتعاون الوكلاء. +- **التكامل**: تعزز قدرات الوكلاء من خلال دمج الأدوات بسلاسة في سير عملهم. +- **القابلية للتخصيص**: توفر المرونة لتطوير أدوات مخصصة أو استخدام الأدوات الموجودة، لتلبية الاحتياجات المحددة للوكلاء. +- **معالجة الأخطاء**: تتضمن آليات معالجة أخطاء قوية لضمان التشغيل السلس. +- **آلية التخزين المؤقت**: تتميز بتخزين مؤقت ذكي لتحسين الأداء وتقليل العمليات المتكررة. +- **الدعم غير المتزامن**: تتعامل مع الأدوات المتزامنة وغير المتزامنة، مما يُمكّن العمليات غير الحاجبة. + +## استخدام أدوات CrewAI + +لتعزيز قدرات وكلائك بأدوات CrewAI، ابدأ بتثبيت حزمة الأدوات الإضافية: + +```bash +pip install 'crewai[tools]' +``` + +إليك مثالًا يوضح استخدامها: + +```python Code +import os +from crewai import Agent, Task, Crew +# استيراد أدوات crewAI +from crewai_tools import ( + DirectoryReadTool, + FileReadTool, + SerperDevTool, + WebsiteSearchTool +) + +# إعداد مفاتيح API +os.environ["SERPER_API_KEY"] = "Your Key" # serper.dev API key +os.environ["OPENAI_API_KEY"] = "Your Key" + +# إنشاء الأدوات +docs_tool = DirectoryReadTool(directory='./blog-posts') +file_tool = FileReadTool() +search_tool = SerperDevTool() +web_rag_tool = WebsiteSearchTool() + +# إنشاء الوكلاء +researcher = Agent( + role='Market Research Analyst', + goal='Provide up-to-date market analysis of the AI industry', + backstory='An expert analyst with a keen eye for market trends.', + tools=[search_tool, web_rag_tool], + verbose=True +) + +writer = Agent( + role='Content Writer', + goal='Craft engaging blog posts about the AI industry', + backstory='A skilled writer with a passion for technology.', + tools=[docs_tool, file_tool], + verbose=True +) + +# تعريف المهام +research = Task( + description='Research the latest trends in the AI industry and provide a summary.', + expected_output='A summary of the top 3 trending developments in the AI industry with a unique perspective on their significance.', + agent=researcher +) + +write = Task( + description='Write an engaging blog post about the AI industry, based on the research analyst\'s summary. Draw inspiration from the latest blog posts in the directory.', + expected_output='A 4-paragraph blog post formatted in markdown with engaging, informative, and accessible content, avoiding complex jargon.', + agent=writer, + output_file='blog-posts/new_post.md' +) + +# تجميع طاقم مع تفعيل التخطيط +crew = Crew( + agents=[researcher, writer], + tasks=[research, write], + verbose=True, + planning=True, +) + +# تنفيذ المهام +crew.kickoff() +``` + +## أدوات CrewAI المتاحة + +- **معالجة الأخطاء**: جميع الأدوات مبنية بقدرات معالجة الأخطاء، مما يسمح للوكلاء بإدارة الاستثناءات بسلاسة ومتابعة مهامهم. +- **آلية التخزين المؤقت**: جميع الأدوات تدعم التخزين المؤقت، مما يُمكّن الوكلاء من إعادة استخدام النتائج المحصلة سابقًا بكفاءة، مما يقلل الحمل على الموارد الخارجية ويسرّع وقت التنفيذ. يمكنك أيضًا تحديد تحكم أدق في آلية التخزين المؤقت باستخدام خاصية `cache_function` على الأداة. + +إليك قائمة بالأدوات المتاحة وأوصافها: + +| الأداة | الوصف | +| :------------------------------- | :--------------------------------------------------------------------------------------------- | +| **ApifyActorsTool** | أداة تدمج Apify Actors مع سير عملك لمهام استخراج البيانات من الويب والأتمتة. | +| **BrowserbaseLoadTool** | أداة للتفاعل مع المتصفحات واستخراج البيانات منها. | +| **CodeDocsSearchTool** | أداة RAG محسّنة للبحث في وثائق الكود والمستندات التقنية ذات الصلة. | +| **CodeInterpreterTool** | أداة لتفسير كود Python. | +| **ComposioTool** | تُمكّن استخدام أدوات Composio. | +| **CSVSearchTool** | أداة RAG مصممة للبحث في ملفات CSV، مخصصة للتعامل مع البيانات المنظمة. | +| **DALL-E Tool** | أداة لإنشاء الصور باستخدام DALL-E API. | +| **DirectorySearchTool** | أداة RAG للبحث في المجلدات، مفيدة للتنقل في أنظمة الملفات. | +| **DOCXSearchTool** | أداة RAG للبحث في مستندات DOCX، مثالية لمعالجة ملفات Word. | +| **DirectoryReadTool** | تسهّل قراءة ومعالجة هياكل المجلدات ومحتوياتها. | +| **EXASearchTool** | أداة مصممة لإجراء عمليات بحث شاملة عبر مصادر بيانات متنوعة. | +| **FileReadTool** | تُمكّن قراءة واستخراج البيانات من الملفات، مع دعم تنسيقات ملفات متنوعة. | +| **FirecrawlSearchTool** | أداة للبحث في صفحات الويب باستخدام Firecrawl وإرجاع النتائج. | +| **FirecrawlCrawlWebsiteTool** | أداة لزحف صفحات الويب باستخدام Firecrawl. | +| **FirecrawlScrapeWebsiteTool** | أداة لاستخراج محتوى عناوين URL لصفحات الويب باستخدام Firecrawl. | +| **GithubSearchTool** | أداة RAG للبحث في مستودعات GitHub، مفيدة لبحث الكود والوثائق. | +| **SerperDevTool** | أداة متخصصة لأغراض التطوير، مع وظائف محددة قيد التطوير. | +| **TXTSearchTool** | أداة RAG مركّزة على البحث في ملفات النص (.txt)، مناسبة للبيانات غير المنظمة. | +| **JSONSearchTool** | أداة RAG مصممة للبحث في ملفات JSON، تخدم التعامل مع البيانات المنظمة. | +| **LlamaIndexTool** | تُمكّن استخدام أدوات LlamaIndex. | +| **MDXSearchTool** | أداة RAG مخصصة للبحث في ملفات Markdown (MDX)، مفيدة للوثائق. | +| **PDFSearchTool** | أداة RAG للبحث في مستندات PDF، مثالية لمعالجة المستندات الممسوحة ضوئيًا. | +| **PGSearchTool** | أداة RAG محسّنة للبحث في قواعد بيانات PostgreSQL، مناسبة لاستعلامات قواعد البيانات. | +| **Vision Tool** | أداة لإنشاء الصور باستخدام DALL-E API. | +| **RagTool** | أداة RAG للأغراض العامة قادرة على التعامل مع مصادر وأنواع بيانات متنوعة. | +| **ScrapeElementFromWebsiteTool** | تُمكّن استخراج عناصر محددة من المواقع، مفيدة لاستخراج البيانات المستهدف. | +| **ScrapeWebsiteTool** | تسهّل استخراج المواقع بالكامل، مثالية لجمع البيانات الشامل. | +| **WebsiteSearchTool** | أداة RAG للبحث في محتوى المواقع، محسّنة لاستخراج بيانات الويب. | +| **XMLSearchTool** | أداة RAG مصممة للبحث في ملفات XML، مناسبة لتنسيقات البيانات المنظمة. | +| **YoutubeChannelSearchTool** | أداة RAG للبحث في قنوات YouTube، مفيدة لتحليل محتوى الفيديو. | +| **YoutubeVideoSearchTool** | أداة RAG للبحث في مقاطع فيديو YouTube، مثالية لاستخراج بيانات الفيديو. | + +## إنشاء أدواتك الخاصة + + + يمكن للمطورين إنشاء `أدوات مخصصة` مصممة خصيصًا لاحتياجات وكلائهم أو + استخدام الخيارات الجاهزة. + + +هناك طريقتان رئيسيتان لإنشاء أداة CrewAI: + +### الوراثة من `BaseTool` + +```python Code +from crewai.tools import BaseTool +from pydantic import BaseModel, Field + +class MyToolInput(BaseModel): + """Input schema for MyCustomTool.""" + argument: str = Field(..., description="Description of the argument.") + +class MyCustomTool(BaseTool): + name: str = "Name of my tool" + description: str = "What this tool does. It's vital for effective utilization." + args_schema: Type[BaseModel] = MyToolInput + + def _run(self, argument: str) -> str: + # منطق أداتك هنا + return "Tool's result" +``` + +## دعم الأدوات غير المتزامنة + +يدعم CrewAI الأدوات غير المتزامنة، مما يتيح لك تنفيذ أدوات تجري عمليات غير حاجبة مثل طلبات الشبكة وعمليات الإدخال/الإخراج على الملفات أو عمليات async أخرى بدون حجب مسار التنفيذ الرئيسي. + +### إنشاء أدوات غير متزامنة + +يمكنك إنشاء أدوات غير متزامنة بطريقتين: + +#### 1. استخدام مزيّن `tool` مع دوال Async + +```python Code +from crewai.tools import tool + +@tool("fetch_data_async") +async def fetch_data_async(query: str) -> str: + """Asynchronously fetch data based on the query.""" + # محاكاة عملية غير متزامنة + await asyncio.sleep(1) + return f"Data retrieved for {query}" +``` + +#### 2. تنفيذ طرق Async في فئات الأدوات المخصصة + +```python Code +from crewai.tools import BaseTool + +class AsyncCustomTool(BaseTool): + name: str = "async_custom_tool" + description: str = "An asynchronous custom tool" + + async def _run(self, query: str = "") -> str: + """Asynchronously run the tool""" + # تنفيذك غير المتزامن هنا + await asyncio.sleep(1) + return f"Processed {query} asynchronously" +``` + +### استخدام الأدوات غير المتزامنة + +تعمل الأدوات غير المتزامنة بسلاسة في كل من سير عمل الطاقم القياسي وسير عمل التدفق: + +```python Code +# في طاقم قياسي +agent = Agent(role="researcher", tools=[async_custom_tool]) + +# في تدفق +class MyFlow(Flow): + @start() + async def begin(self): + crew = Crew(agents=[agent]) + result = await crew.kickoff_async() + return result +``` + +يتعامل إطار عمل CrewAI تلقائيًا مع تنفيذ الأدوات المتزامنة وغير المتزامنة، لذا لا تحتاج للقلق بشأن كيفية استدعائها بشكل مختلف. + +### استخدام مزيّن `tool` + +```python Code +from crewai.tools import tool +@tool("Name of my tool") +def my_tool(question: str) -> str: + """Clear description for what this tool is useful for, your agent will need this information to use it.""" + # منطق الدالة هنا + return "Result from your custom tool" +``` + +### آلية التخزين المؤقت المخصصة + + + يمكن للأدوات اختياريًا تنفيذ `cache_function` لضبط سلوك + التخزين المؤقت. تحدد هذه الدالة متى يتم تخزين النتائج مؤقتًا بناءً على شروط + محددة، مما يوفر تحكمًا دقيقًا في منطق التخزين المؤقت. + + +```python Code +from crewai.tools import tool + +@tool +def multiplication_tool(first_number: int, second_number: int) -> str: + """Useful for when you need to multiply two numbers together.""" + return first_number * second_number + +def cache_func(args, result): + # في هذه الحالة، نخزّن النتيجة مؤقتًا فقط إذا كانت من مضاعفات 2 + cache = result % 2 == 0 + return cache + +multiplication_tool.cache_function = cache_func + +writer1 = Agent( + role="Writer", + goal="You write lessons of math for kids.", + backstory="You're an expert in writing and you love to teach kids but you know nothing of math.", + tools=[multiplication_tool], + allow_delegation=False, + ) + #... +``` + +## الخلاصة + +الأدوات محورية في توسيع قدرات وكلاء CrewAI، مما يمكّنهم من تنفيذ مجموعة واسعة من المهام والتعاون بفعالية. +عند بناء حلول مع CrewAI، استفد من كل من الأدوات المخصصة والموجودة لتمكين وكلائك وتعزيز نظام الذكاء الاصطناعي البيئي. فكّر في استخدام معالجة الأخطاء وآليات التخزين المؤقت ومرونة معاملات الأدوات لتحسين أداء وقدرات وكلائك. diff --git a/docs/ar/concepts/training.mdx b/docs/ar/concepts/training.mdx new file mode 100644 index 000000000..019532348 --- /dev/null +++ b/docs/ar/concepts/training.mdx @@ -0,0 +1,197 @@ +--- +title: التدريب +description: تعرّف على كيفية تدريب وكلاء CrewAI من خلال تقديم ملاحظات مبكرة والحصول على نتائج متسقة. +icon: dumbbell +mode: "wide" +--- + +## نظرة عامة + +تتيح لك ميزة التدريب في CrewAI تدريب وكلاء الذكاء الاصطناعي باستخدام واجهة سطر الأوامر (CLI). +بتشغيل الأمر `crewai train -n `، يمكنك تحديد عدد التكرارات لعملية التدريب. + +أثناء التدريب، يستخدم CrewAI تقنيات لتحسين أداء وكلائك مع التغذية الراجعة البشرية. +يساعد هذا الوكلاء على تحسين فهمهم واتخاذ القرارات وحل المشكلات. + +### تدريب طاقمك باستخدام CLI + +لاستخدام ميزة التدريب، اتبع الخطوات التالية: + +1. افتح الطرفية أو موجه الأوامر. +2. انتقل إلى المجلد حيث يقع مشروع CrewAI. +3. شغّل الأمر التالي: + +```shell +crewai train -n -f +``` + + استبدل `` بعدد تكرارات التدريب المرغوب و`` باسم الملف المناسب المنتهي بـ `.pkl`. + + + + إذا حذفت `-f`، فإن المخرجات تُحفظ افتراضيًا في `trained_agents_data.pkl` في مجلد العمل الحالي. يمكنك تمرير مسار مطلق للتحكم في مكان كتابة الملف. + + +### تدريب طاقمك برمجيًا + +لتدريب طاقمك برمجيًا، استخدم الخطوات التالية: + +1. حدد عدد التكرارات للتدريب. +2. حدد معاملات الإدخال لعملية التدريب. +3. نفّذ أمر التدريب داخل كتلة try-except للتعامل مع الأخطاء المحتملة. + +```python Code +n_iterations = 2 +inputs = {"topic": "CrewAI Training"} +filename = "your_model.pkl" + +try: + YourCrewName_Crew().crew().train( + n_iterations=n_iterations, + inputs=inputs, + filename=filename + ) + +except Exception as e: + raise Exception(f"An error occurred while training the crew: {e}") +``` + +## كيف تُستخدم بيانات التدريب من قبل الوكلاء + +يستخدم CrewAI مخرجات التدريب بطريقتين: أثناء التدريب لدمج ملاحظاتك البشرية، وبعد التدريب لتوجيه الوكلاء باقتراحات موحدة. + +### تدفق بيانات التدريب + +```mermaid +flowchart TD + A["Start training
CLI: crewai train -n -f
or Python: crew.train(...)"] --> B["Setup training mode
- task.human_input = true
- disable delegation
- init training_data.pkl + trained file"] + + subgraph "Iterations" + direction LR + C["Iteration i
initial_output"] --> D["User human_feedback"] + D --> E["improved_output"] + E --> F["Append to training_data.pkl
by agent_id and iteration"] + end + + B --> C + F --> G{"More iterations?"} + G -- "Yes" --> C + G -- "No" --> H["Evaluate per agent
aggregate iterations"] + + H --> I["Consolidate
suggestions[] + quality + final_summary"] + I --> J["Save by agent role to trained file
(default: trained_agents_data.pkl)"] + + J --> K["Normal (non-training) runs"] + K --> L["Auto-load suggestions
from trained_agents_data.pkl"] + L --> M["Append to prompt
for consistent improvements"] +``` + +### أثناء تشغيلات التدريب + +- في كل تكرار، يسجل النظام لكل وكيل: + - `initial_output`: الإجابة الأولى للوكيل + - `human_feedback`: ملاحظاتك المضمّنة عند الطلب + - `improved_output`: إجابة المتابعة للوكيل بعد الملاحظات +- تُخزن هذه البيانات في ملف عمل باسم `training_data.pkl` مفهرس بمعرّف الوكيل الداخلي والتكرار. +- أثناء نشاط التدريب، يُلحق الوكيل تلقائيًا ملاحظاتك البشرية السابقة بأمره لتطبيق تلك التعليمات في المحاولات اللاحقة ضمن جلسة التدريب. + التدريب تفاعلي: تُعيّن المهام `human_input = true`، لذا سيتوقف التشغيل في بيئة غير تفاعلية بانتظار مدخلات المستخدم. + +### بعد اكتمال التدريب + +- عند انتهاء `train(...)`، يقيّم CrewAI بيانات التدريب المجمعة لكل وكيل وينتج نتيجة موحدة تحتوي على: + - `suggestions`: تعليمات واضحة وقابلة للتنفيذ مستخلصة من ملاحظاتك والفرق بين المخرجات الأولية/المحسنة + - `quality`: درجة من 0-10 تعكس التحسن + - `final_summary`: مجموعة خطوات عمل تفصيلية للمهام المستقبلية +- تُحفظ هذه النتائج الموحدة في اسم الملف الذي تمرره إلى `train(...)` (الافتراضي عبر CLI هو `trained_agents_data.pkl`). تُفهرس الإدخالات بدور الوكيل `role` لتطبيقها عبر الجلسات. +- أثناء التنفيذ العادي (غير التدريب)، يحمّل كل وكيل تلقائيًا `suggestions` الموحدة ويلحقها بأمر المهمة كتعليمات إلزامية. يمنحك هذا تحسينات متسقة بدون تغيير تعريفات الوكلاء. + +### ملخص الملفات + +- `training_data.pkl` (مؤقت، لكل جلسة): + - الهيكل: `agent_id -> { iteration_number: { initial_output, human_feedback, improved_output } }` + - الغرض: التقاط البيانات الخام والملاحظات البشرية أثناء التدريب + - الموقع: يُحفظ في مجلد العمل الحالي (CWD) +- `trained_agents_data.pkl` (أو اسم ملفك المخصص): + - الهيكل: `agent_role -> { suggestions: string[], quality: number, final_summary: string }` + - الغرض: استمرار التوجيه الموحد للتشغيلات المستقبلية + - الموقع: يُكتب في CWD افتراضيًا؛ استخدم `-f` لتعيين مسار مخصص (بما في ذلك المطلق) + +## اعتبارات نماذج اللغة الصغيرة + + + عند استخدام نماذج لغة أصغر (≤7 مليار معامل) لتقييم بيانات التدريب، كن على علم أنها قد تواجه تحديات في إنتاج مخرجات منظمة واتباع التعليمات المعقدة. + + +### قيود النماذج الصغيرة في تقييم التدريب + + + + غالبًا ما تواجه النماذج الأصغر صعوبة في إنتاج استجابات JSON صالحة مطلوبة لتقييمات التدريب المنظمة، مما يؤدي إلى أخطاء تحليل وبيانات غير مكتملة. + + + قد توفر النماذج تحت 7 مليار معامل تقييمات أقل دقة مع عمق استدلال محدود مقارنة بالنماذج الأكبر. + + + قد لا تُتبع معايير تقييم التدريب المعقدة بالكامل أو تُراعى من قبل النماذج الأصغر. + + + قد تفتقر التقييمات عبر تكرارات تدريب متعددة إلى الاتساق مع النماذج الأصغر. + + + +### توصيات للتدريب + + + + لجودة تدريب مثالية وتقييمات موثوقة، نوصي بشدة باستخدام نماذج بحد أدنى 7 مليار معامل أو أكبر: + + ```python + from crewai import Agent, Crew, Task, LLM + + # الحد الأدنى الموصى به لتقييم التدريب + llm = LLM(model="mistral/open-mistral-7b") + + # خيارات أفضل لتقييم تدريب موثوق + llm = LLM(model="anthropic/claude-3-sonnet-20240229-v1:0") + llm = LLM(model="gpt-4o") + + # استخدم هذا LLM مع وكلائك + agent = Agent( + role="Training Evaluator", + goal="Provide accurate training feedback", + llm=llm + ) + ``` + + + توفر النماذج الأكثر قوة ملاحظات أعلى جودة مع استدلال أفضل، مما يؤدي إلى تكرارات تدريب أكثر فعالية. + + + + إذا كان يجب عليك استخدام نماذج أصغر لتقييم التدريب، كن على علم بهذه القيود: + + ```python + # استخدام نموذج أصغر (توقع بعض القيود) + llm = LLM(model="huggingface/microsoft/Phi-3-mini-4k-instruct") + ``` + + + بينما يتضمن CrewAI تحسينات للنماذج الصغيرة، توقع نتائج تقييم أقل موثوقية ودقة قد تتطلب تدخلاً بشريًا أكبر أثناء التدريب. + + + + +### نقاط مهمة يجب ملاحظتها + +- **متطلب العدد الصحيح الموجب:** تأكد من أن عدد التكرارات (`n_iterations`) هو عدد صحيح موجب. سيرمي الكود `ValueError` إذا لم يتحقق هذا الشرط. +- **متطلب اسم الملف:** تأكد من أن اسم الملف ينتهي بـ `.pkl`. سيرمي الكود `ValueError` إذا لم يتحقق هذا الشرط. +- **معالجة الأخطاء:** يتعامل الكود مع أخطاء العمليات الفرعية والاستثناءات غير المتوقعة، ويوفر رسائل خطأ للمستخدم. +- يُطبق التوجيه المدرّب في وقت الأمر؛ لا يعدّل تهيئة وكيل Python/YAML. +- يحمّل الوكلاء تلقائيًا الاقتراحات المدربة من ملف باسم `trained_agents_data.pkl` الموجود في مجلد العمل الحالي. إذا درّبت إلى اسم ملف مختلف، أعد تسميته إلى `trained_agents_data.pkl` قبل التشغيل، أو اضبط المحمّل في الكود. +- يمكنك تغيير اسم ملف المخرجات عند استدعاء `crewai train` بـ `-f/--filename`. المسارات المطلقة مدعومة إذا أردت الحفظ خارج CWD. + +من المهم ملاحظة أن عملية التدريب قد تستغرق بعض الوقت، اعتمادًا على تعقيد وكلائك وستتطلب أيضًا ملاحظاتك في كل تكرار. + +بمجرد اكتمال التدريب، سيكون وكلاؤك مجهزين بقدرات ومعرفة محسّنة، وجاهزين لمعالجة المهام المعقدة وتقديم رؤى أكثر اتساقًا وقيمة. + +تذكر تحديث وإعادة تدريب وكلائك بانتظام لضمان بقائهم على اطلاع بأحدث المعلومات والتطورات في المجال. diff --git a/docs/ar/enterprise/features/agent-repositories.mdx b/docs/ar/enterprise/features/agent-repositories.mdx new file mode 100644 index 000000000..ff8e9e5db --- /dev/null +++ b/docs/ar/enterprise/features/agent-repositories.mdx @@ -0,0 +1,155 @@ +--- +title: 'مستودعات الوكلاء' +description: 'تعرّف على كيفية استخدام مستودعات الوكلاء لمشاركة وإعادة استخدام وكلائك عبر الفرق والمشاريع' +icon: 'people-group' +mode: "wide" +--- + +تتيح مستودعات الوكلاء لمستخدمي المؤسسات تخزين ومشاركة وإعادة استخدام تعريفات الوكلاء عبر الفرق والمشاريع. تُمكّن هذه الميزة المؤسسات من الاحتفاظ بمكتبة مركزية من الوكلاء الموحدين، مما يعزز الاتساق ويقلل من ازدواجية الجهود. + + + ![Agent Repositories](/images/enterprise/agent-repositories.png) + + +## فوائد مستودعات الوكلاء + +- **التوحيد**: الحفاظ على تعريفات وكلاء متسقة عبر مؤسستك +- **إعادة الاستخدام**: إنشاء وكيل مرة واحدة واستخدامه في أطقم ومشاريع متعددة +- **الحوكمة**: تطبيق سياسات على مستوى المؤسسة لتهيئات الوكلاء +- **التعاون**: تمكين الفرق من المشاركة والبناء على عمل بعضهم البعض + +## إنشاء واستخدام مستودعات الوكلاء + +1. يجب أن يكون لديك حساب في CrewAI، جرّب [الخطة المجانية](https://app.crewai.com). +2. أنشئ وكلاء بأدوار وأهداف محددة لسير عملك. +3. هيّئ الأدوات والقدرات لكل مساعد متخصص. +4. انشر الوكلاء عبر المشاريع من خلال الواجهة المرئية أو تكامل API. + + + ![Agent Repositories](/images/enterprise/create-agent-repository.png) + + + +### تحميل الوكلاء من المستودعات + +يمكنك تحميل الوكلاء من المستودعات في الكود باستخدام معامل `from_repository` للتشغيل محليًا: + +```python +from crewai import Agent + +# إنشاء وكيل بتحميله من مستودع +# يتم تحميل الوكيل بجميع إعداداته المحددة مسبقًا +researcher = Agent( + from_repository="market-research-agent" +) +``` + +### تجاوز إعدادات المستودع + +يمكنك تجاوز إعدادات محددة من المستودع بتوفيرها في التهيئة: + +```python +researcher = Agent( + from_repository="market-research-agent", + goal="Research the latest trends in AI development", # تجاوز هدف المستودع + verbose=True # إضافة إعداد غير موجود في المستودع +) +``` + +### مثال: إنشاء طاقم مع وكلاء المستودع + +```python +from crewai import Crew, Agent, Task + +# تحميل الوكلاء من المستودعات +researcher = Agent( + from_repository="market-research-agent" +) + +writer = Agent( + from_repository="content-writer-agent" +) + +# إنشاء المهام +research_task = Task( + description="Research the latest trends in AI", + agent=researcher +) + +writing_task = Task( + description="Write a comprehensive report based on the research", + agent=writer +) + +# إنشاء الطاقم +crew = Crew( + agents=[researcher, writer], + tasks=[research_task, writing_task], + verbose=True +) + +# تشغيل الطاقم +result = crew.kickoff() +``` + +### مثال: استخدام `kickoff()` مع وكلاء المستودع + +يمكنك أيضًا استخدام وكلاء المستودع مباشرة مع طريقة `kickoff()` للتفاعلات الأبسط: + +```python +from crewai import Agent +from pydantic import BaseModel +from typing import List + +# تعريف تنسيق مخرجات منظم +class MarketAnalysis(BaseModel): + key_trends: List[str] + opportunities: List[str] + recommendation: str + +# تحميل وكيل من المستودع +analyst = Agent( + from_repository="market-analyst-agent", + verbose=True +) + +# الحصول على استجابة حرة +result = analyst.kickoff("Analyze the AI market in 2025") +print(result.raw) # الوصول إلى الاستجابة الخام + +# الحصول على مخرجات منظمة +structured_result = analyst.kickoff( + "Provide a structured analysis of the AI market in 2025", + response_format=MarketAnalysis +) + +# الوصول إلى البيانات المنظمة +print(f"Key Trends: {structured_result.pydantic.key_trends}") +print(f"Recommendation: {structured_result.pydantic.recommendation}") +``` + +## أفضل الممارسات + +1. **اصطلاح التسمية**: استخدم أسماء واضحة ووصفية لوكلاء المستودع +2. **التوثيق**: أدرج أوصافًا شاملة لكل وكيل +3. **إدارة الأدوات**: تأكد من توفر الأدوات المشار إليها بواسطة وكلاء المستودع في بيئتك +4. **التحكم في الوصول**: أدر الصلاحيات لضمان أن أعضاء الفريق المصرّح لهم فقط يمكنهم تعديل وكلاء المستودع + +## إدارة المؤسسة + +للتبديل بين المؤسسات أو عرض مؤسستك الحالية، استخدم واجهة سطر أوامر CrewAI: + +```bash +# عرض المؤسسة الحالية +crewai org current + +# التبديل إلى مؤسسة مختلفة +crewai org switch + +# عرض جميع المؤسسات المتاحة +crewai org list +``` + + +عند تحميل الوكلاء من المستودعات، يجب أن تكون مصادقًا ومتحولًا إلى المؤسسة الصحيحة. إذا تلقيت أخطاء، تحقق من حالة المصادقة وإعدادات المؤسسة باستخدام أوامر CLI أعلاه. + diff --git a/docs/ar/enterprise/features/automations.mdx b/docs/ar/enterprise/features/automations.mdx new file mode 100644 index 000000000..8f5ed5fa7 --- /dev/null +++ b/docs/ar/enterprise/features/automations.mdx @@ -0,0 +1,104 @@ +--- +title: الأتمتة +description: "إدارة ونشر ومراقبة أطقمك المباشرة (الأتمتة) في مكان واحد." +icon: "rocket" +mode: "wide" +--- + +## نظرة عامة + +الأتمتة هي مركز العمليات المباشرة لأطقمك المنشورة. استخدمها للنشر من GitHub أو ملف ZIP، وإدارة متغيرات البيئة، وإعادة النشر عند الحاجة، ومراقبة حالة كل أتمتة. + + + ![Automations Overview](/images/enterprise/automations-overview.png) + + + +## طرق النشر + +### النشر من GitHub + +استخدم هذا للمشاريع ذات التحكم في الإصدارات والنشر المستمر. + + + + انقر على Configure GitHub وصرّح بالوصول. + + + اختر المستودع والفرع الذي تريد النشر منه. + + + فعّل النشر التلقائي للالتزامات الجديدة لإرسال التحديثات مع كل دفع. + + + أضف المتغيرات السرية فرديًا أو استخدم العرض الجماعي لمتغيرات متعددة. + + + انقر على Deploy لإنشاء الأتمتة المباشرة. + + + + + ![GitHub Deployment](/images/enterprise/deploy-from-github.png) + + +### النشر من ZIP + +انشر بسرعة بدون Git — ارفع حزمة مضغوطة من مشروعك. + + + + اختر أرشيف ZIP من جهازك. + + + وفّر أي متغيرات أو مفاتيح مطلوبة. + + + انقر على Deploy لإنشاء الأتمتة المباشرة. + + + + + ![ZIP Deployment](/images/enterprise/deploy-from-zip.png) + + +## لوحة تحكم الأتمتة + +يعرض الجدول جميع الأتمتة المباشرة مع التفاصيل الرئيسية: + +- **CREW**: اسم الأتمتة +- **STATUS**: متصل / فشل / قيد التنفيذ +- **URL**: نقطة نهاية التشغيل/الحالة +- **TOKEN**: رمز الأتمتة +- **ACTIONS**: إعادة النشر، الحذف، والمزيد + +استخدم عناصر التحكم في أعلى اليمين للتصفية والبحث: + +- البحث بالاسم +- التصفية حسب الحالة +- التصفية حسب المصدر (GitHub / Studio / ZIP) + +بعد النشر، يمكنك عرض تفاصيل الأتمتة واستخدام القائمة المنسدلة **الخيارات** لـ `الدردشة مع هذا الطاقم`، `تصدير مكون React` و`التصدير كـ MCP`. + + + ![Automations Table](/images/enterprise/automations-table.png) + + +## أفضل الممارسات + +- فضّل نشر GitHub للتحكم في الإصدارات وCI/CD +- استخدم إعادة النشر للتقدم بعد تحديثات الكود أو التهيئة أو اضبطه على النشر التلقائي مع كل دفع + +## ذات صلة + + + + انشر طاقمًا من GitHub أو ملف ZIP. + + + شغّل الأتمتة عبر webhooks أو API. + + + بث الأحداث والتحديثات في الوقت الفعلي إلى أنظمتك. + + diff --git a/docs/ar/enterprise/features/crew-studio.mdx b/docs/ar/enterprise/features/crew-studio.mdx new file mode 100644 index 000000000..ab945ba31 --- /dev/null +++ b/docs/ar/enterprise/features/crew-studio.mdx @@ -0,0 +1,88 @@ +--- +title: استوديو الطاقم +description: "إنشاء أتمتة جديدة بمساعدة الذكاء الاصطناعي ومحرر مرئي واختبار متكامل." +icon: "pencil" +mode: "wide" +--- + +## نظرة عامة + +استوديو الطاقم هو مساحة عمل تفاعلية بمساعدة الذكاء الاصطناعي لإنشاء أتمتة جديدة من الصفر باستخدام اللغة الطبيعية ومحرر سير عمل مرئي. + + + ![Crew Studio Overview](/images/enterprise/crew-studio-overview.png) + + +## الإنشاء المبني على الأوامر النصية + +- صِف الأتمتة التي تريدها؛ يقوم الذكاء الاصطناعي بإنشاء الوكلاء والمهام والأدوات. +- استخدم الإدخال الصوتي عبر أيقونة الميكروفون إذا فضّلت ذلك. +- ابدأ من أوامر مدمجة لحالات الاستخدام الشائعة. + + + ![Prompt Builder](/images/enterprise/crew-studio-prompt.png) + + +## المحرر المرئي + +يعكس اللوح سير العمل كعُقد وأسهم مع ثلاث لوحات داعمة تتيح لك تهيئة سير العمل بسهولة بدون كتابة كود؛ ما يُعرف بـ "**البرمجة الحدسية لوكلاء الذكاء الاصطناعي**". + +يمكنك استخدام وظيفة السحب والإفلات لإضافة الوكلاء والمهام والأدوات إلى اللوح أو استخدام قسم الدردشة لبناء الوكلاء. يتشارك كلا النهجين الحالة ويمكن استخدامهما بالتبادل. + +- **أفكار AI (يسار)**: الاستدلال المتدفق أثناء تصميم سير العمل +- **اللوح (المركز)**: الوكلاء والمهام كعقد متصلة +- **الموارد (يمين)**: مكونات السحب والإفلات (وكلاء، مهام، أدوات) + + + ![Visual Canvas](/images/enterprise/crew-studio-canvas.png) + + +## التنفيذ والتصحيح + +انتقل إلى عرض التنفيذ لتشغيل سير العمل ومراقبته: + +- الجدول الزمني للأحداث +- سجلات مفصلة (التفاصيل، الرسائل، البيانات الخام) +- اختبارات محلية قبل النشر + + + ![Execution View](/images/enterprise/crew-studio-execution.png) + + +## النشر والتصدير + +- انشر لنشر أتمتة مباشرة +- حمّل المصدر كملف ZIP للتطوير المحلي أو التخصيص + + + ![Publish & Download](/images/enterprise/crew-studio-publish.png) + + +بعد النشر، يمكنك عرض تفاصيل الأتمتة واستخدام القائمة المنسدلة **الخيارات** لـ `الدردشة مع هذا الطاقم`، `تصدير مكون React` و`التصدير كـ MCP`. + + + ![Published Automation](/images/enterprise/crew-studio-published.png) + + +## أفضل الممارسات + +- كرر بسرعة في الاستوديو؛ انشر فقط عندما يكون مستقرًا +- اقصر الأدوات على الحد الأدنى من الصلاحيات المطلوبة +- استخدم التتبعات للتحقق من السلوك والأداء + +## ذات صلة + + + + تفعيل استوديو الطاقم. + + + بناء طاقم. + + + نشر طاقم من GitHub أو ملف ZIP. + + + تصدير مكون React. + + diff --git a/docs/ar/enterprise/features/flow-hitl-management.mdx b/docs/ar/enterprise/features/flow-hitl-management.mdx new file mode 100644 index 000000000..6b4096abf --- /dev/null +++ b/docs/ar/enterprise/features/flow-hitl-management.mdx @@ -0,0 +1,558 @@ +--- +title: "إدارة HITL للتدفقات" +description: "مراجعة بشرية بمستوى المؤسسات للتدفقات مع إشعارات البريد الإلكتروني أولاً وقواعد التوجيه وإمكانيات الاستجابة التلقائية" +icon: "users-gear" +mode: "wide" +--- + + +تتطلب ميزات إدارة Flow HITL مزيّن `@human_feedback`، المتاح في **CrewAI الإصدار 1.8.0 أو أحدث**. تنطبق هذه الميزات تحديدًا على **التدفقات (Flows)**، وليس الأطقم (Crews). + + +يوفر CrewAI Enterprise نظامًا شاملًا لإدارة الإنسان في الحلقة (HITL) للتدفقات يحوّل سير عمل الذكاء الاصطناعي إلى عمليات تعاونية بين الإنسان والذكاء الاصطناعي. تستخدم المنصة **بنية البريد الإلكتروني أولاً** التي تمكّن أي شخص لديه عنوان بريد إلكتروني من الرد على طلبات المراجعة — بدون الحاجة لحساب على المنصة. + +## نظرة عامة + + + + يمكن للمستجيبين الرد مباشرة على رسائل الإشعار لتقديم الملاحظات + + + توجيه الطلبات إلى بريد إلكتروني محدد بناءً على أنماط الطرق أو حالة التدفق + + + تهيئة استجابات احتياطية تلقائية عندما لا يرد أي شخص في الوقت المحدد + + + +### الفوائد الرئيسية + +- **نموذج ذهني بسيط**: عناوين البريد الإلكتروني عالمية؛ لا حاجة لإدارة مستخدمين أو أدوار المنصة +- **مستجيبون خارجيون**: يمكن لأي شخص لديه بريد إلكتروني الرد، حتى غير مستخدمي المنصة +- **تعيين ديناميكي**: سحب بريد المعيّن مباشرة من حالة التدفق (مثل `sales_rep_email`) +- **تهيئة مخفضة**: إعدادات أقل للتهيئة، وقت أسرع للقيمة +- **البريد الإلكتروني كقناة رئيسية**: يفضل معظم المستخدمين الرد عبر البريد الإلكتروني بدلاً من تسجيل الدخول إلى لوحة التحكم + +## إعداد نقاط المراجعة البشرية في التدفقات + +هيّئ نقاط تفتيش المراجعة البشرية داخل تدفقاتك باستخدام مزيّن `@human_feedback`. عندما يصل التنفيذ إلى نقطة مراجعة، يتوقف النظام ويُخطر المعيّن عبر البريد الإلكتروني وينتظر الاستجابة. + +```python +from crewai.flow.flow import Flow, start, listen, or_ +from crewai.flow.human_feedback import human_feedback, HumanFeedbackResult + +class ContentApprovalFlow(Flow): + @start() + def generate_content(self): + return "Generated marketing copy for Q1 campaign..." + + @human_feedback( + message="Please review this content for brand compliance:", + emit=["approved", "rejected", "needs_revision"], + ) + @listen(or_("generate_content", "needs_revision")) + def review_content(self): + return "Marketing copy for review..." + + @listen("approved") + def publish_content(self, result: HumanFeedbackResult): + print(f"Publishing approved content. Reviewer notes: {result.feedback}") + + @listen("rejected") + def archive_content(self, result: HumanFeedbackResult): + print(f"Content rejected. Reason: {result.feedback}") +``` + +للحصول على تفاصيل التنفيذ الكاملة، راجع دليل [التغذية الراجعة البشرية في التدفقات](/ar/learn/human-feedback-in-flows). + +### معاملات المزيّن + +| المعامل | النوع | الوصف | +|-----------|------|-------------| +| `message` | `str` | الرسالة المعروضة للمراجع البشري | +| `emit` | `list[str]` | خيارات الاستجابة الصالحة (تُعرض كأزرار في الواجهة) | + +## تهيئة المنصة + +الوصول إلى تهيئة HITL من: **النشر** ← **الإعدادات** ← **تهيئة الإنسان في الحلقة** + + + HITL Configuration Settings + + +### إشعارات البريد الإلكتروني + +تبديل لتفعيل أو تعطيل إشعارات البريد الإلكتروني لطلبات HITL. + +| الإعداد | الافتراضي | الوصف | +|---------|---------|-------------| +| إشعارات البريد الإلكتروني | مفعّل | إرسال رسائل عند طلب الملاحظات | + + +عند التعطيل، يجب على المستجيبين استخدام واجهة لوحة التحكم أو يجب تهيئة webhooks لأنظمة إشعارات مخصصة. + + +### هدف SLA + +تعيين وقت استجابة مستهدف لأغراض التتبع والمقاييس. + +| الإعداد | الوصف | +|---------|-------------| +| هدف SLA (دقائق) | وقت الاستجابة المستهدف. يُستخدم لمقاييس لوحة التحكم وتتبع SLA | + +اتركه فارغًا لتعطيل تتبع SLA. + +## إشعارات واستجابات البريد الإلكتروني + +يستخدم نظام HITL بنية البريد الإلكتروني أولاً حيث يمكن للمستجيبين الرد مباشرة على رسائل الإشعار. + +### كيف تعمل استجابات البريد الإلكتروني + + + + عند إنشاء طلب HITL، يُرسل بريد إلكتروني إلى المستجيب المعيّن مع محتوى المراجعة والسياق. + + + يتضمن البريد عنوان رد خاص مع رمز موقّع للمصادقة. + + + يرد المستجيب ببساطة على البريد بملاحظاته — بدون حاجة لتسجيل الدخول. + + + تستقبل المنصة الرد، وتتحقق من الرمز الموقّع، وتطابق بريد المرسل. + + + تُسجل الملاحظات ويستمر التدفق مع مدخلات الإنسان. + + + +### تنسيق الاستجابة + +يمكن للمستجيبين الرد بـ: + +- **خيار emit**: إذا تطابق الرد مع خيار `emit` (مثل "approved")، يُستخدم مباشرة +- **نص حر**: أي نص استجابة يُمرر إلى التدفق كملاحظات +- **نص عادي**: يُستخدم السطر الأول من نص الرد كملاحظات + +### رسائل التأكيد + +بعد معالجة الرد، يستلم المستجيب رسالة تأكيد تشير إلى ما إذا تم إرسال الملاحظات بنجاح أو حدث خطأ. + +### أمان رمز البريد + +- الرموز موقّعة تشفيريًا للأمان +- تنتهي صلاحية الرموز بعد 7 أيام +- يجب أن يتطابق بريد المرسل مع البريد المصرّح به في الرمز +- تُرسل رسائل تأكيد/خطأ بعد المعالجة + +## قواعد التوجيه + +توجيه طلبات HITL إلى عناوين بريد إلكتروني محددة بناءً على أنماط الطرق. + + + HITL Routing Rules Configuration + + +### هيكل القاعدة + +```json +{ + "name": "Approvals to Finance", + "match": { + "method_name": "approve_*" + }, + "assign_to_email": "finance@company.com", + "assign_from_input": "manager_email" +} +``` + +### أنماط المطابقة + +| النمط | الوصف | مثال المطابقة | +|---------|-------------|---------------| +| `approve_*` | حرف بدل (أي أحرف) | `approve_payment`، `approve_vendor` | +| `review_?` | حرف واحد | `review_a`، `review_1` | +| `validate_payment` | مطابقة تامة | `validate_payment` فقط | + +### أولوية التعيين + +1. **تعيين ديناميكي** (`assign_from_input`): إذا تم تهيئته، يسحب البريد من حالة التدفق +2. **بريد ثابت** (`assign_to_email`): يرجع إلى البريد المهيأ +3. **منشئ النشر**: إذا لم تتطابق أي قاعدة، يُستخدم بريد منشئ النشر + +### مثال التعيين الديناميكي + +إذا كانت حالة تدفقك تحتوي على `{"sales_rep_email": "alice@company.com"}`، هيّئ: + +```json +{ + "name": "Route to Sales Rep", + "match": { + "method_name": "review_*" + }, + "assign_from_input": "sales_rep_email" +} +``` + +سيتم تعيين الطلب إلى `alice@company.com` تلقائيًا. + + +**حالة استخدام**: اسحب المعيّن من CRM أو قاعدة البيانات أو خطوة تدفق سابقة لتوجيه المراجعات ديناميكيًا إلى الشخص المناسب. + + +## الاستجابة التلقائية + +الاستجابة تلقائيًا لطلبات HITL إذا لم يستجب أي شخص خلال المهلة المحددة. يضمن هذا عدم تعليق التدفقات إلى أجل غير مسمى. + +### التهيئة + +| الإعداد | الوصف | +|---------|-------------| +| مفعّل | تبديل لتفعيل الاستجابة التلقائية | +| المهلة (دقائق) | الوقت المنتظر قبل الاستجابة التلقائية | +| النتيجة الافتراضية | قيمة الاستجابة (يجب أن تطابق خيار `emit`) | + + + HITL Auto-Response Configuration + + +### حالات الاستخدام + +- **الامتثال لـ SLA**: ضمان عدم تعليق التدفقات إلى أجل غير مسمى +- **الموافقة الافتراضية**: الموافقة التلقائية على الطلبات منخفضة المخاطر بعد انتهاء المهلة +- **التراجع السلس**: المتابعة بافتراضي آمن عندما يكون المراجعون غير متاحين + + +استخدم الاستجابة التلقائية بحذر. فعّلها فقط للمراجعات غير الحرجة حيث تكون الاستجابة الافتراضية مقبولة. + + +## عملية المراجعة + +### واجهة لوحة التحكم + +توفر واجهة مراجعة HITL تجربة نظيفة ومركّزة للمراجعين: + +- **عرض Markdown**: تنسيق غني لمحتوى المراجعة مع تمييز الصيغة +- **لوحة السياق**: عرض حالة التدفق وتاريخ التنفيذ والمعلومات ذات الصلة +- **إدخال الملاحظات**: تقديم ملاحظات وتعليقات مفصلة مع قرارك +- **إجراءات سريعة**: أزرار خيارات emit بنقرة واحدة مع تعليقات اختيارية + + + HITL Pending Requests List + + +### طرق الاستجابة + +يمكن للمراجعين الاستجابة عبر ثلاث قنوات: + +| الطريقة | الوصف | +|--------|-------------| +| **الرد عبر البريد** | الرد مباشرة على رسالة الإشعار | +| **لوحة التحكم** | استخدام واجهة لوحة تحكم المؤسسة | +| **API/Webhook** | استجابة برمجية عبر API | + +### السجل ومسار التدقيق + +يتم تتبع كل تفاعل HITL بجدول زمني كامل: + +- سجل القرارات (موافقة/رفض/مراجعة) +- هوية المراجع والطابع الزمني +- الملاحظات والتعليقات المقدمة +- طريقة الاستجابة (بريد/لوحة تحكم/API) +- مقاييس وقت الاستجابة + +## التحليلات والمراقبة + +تتبع أداء HITL مع تحليلات شاملة. + +### لوحة تحكم الأداء + + + HITL Metrics Dashboard + + + + + مراقبة متوسط وميديان أوقات الاستجابة حسب المراجع أو التدفق. + + + تحليل أنماط حجم المراجعة لتحسين قدرة الفريق. + + + عرض معدلات الموافقة/الرفض عبر أنواع المراجعة المختلفة. + + + تتبع نسبة المراجعات المكتملة ضمن أهداف SLA. + + + +### التدقيق والامتثال + +إمكانيات تدقيق جاهزة للمؤسسات للمتطلبات التنظيمية: + +- سجل قرارات كامل مع الطوابع الزمنية +- التحقق من هوية المراجع +- سجلات تدقيق غير قابلة للتغيير +- إمكانيات التصدير لتقارير الامتثال + +## حالات الاستخدام الشائعة + + + + **حالة الاستخدام**: أتمتة استبيانات الأمان الداخلية مع التحقق البشري + + - يولّد الذكاء الاصطناعي الردود على الاستبيانات الأمنية + - يراجع فريق الأمن ويتحقق من الدقة عبر البريد الإلكتروني + - يتم تجميع الردود المعتمدة في التقديم النهائي + - مسار تدقيق كامل للامتثال + + + + **حالة الاستخدام**: محتوى تسويقي يتطلب مراجعة قانونية/العلامة التجارية + + - يولّد الذكاء الاصطناعي نصوص تسويقية أو محتوى وسائل التواصل + - التوجيه إلى بريد فريق العلامة التجارية لمراجعة النبرة/الأسلوب + - النشر التلقائي عند الموافقة + + + + **حالة الاستخدام**: تقارير النفقات، شروط العقود، تخصيصات الميزانية + + - يعالج الذكاء الاصطناعي مسبقًا ويصنف الطلبات المالية + - التوجيه بناءً على عتبات المبالغ باستخدام التعيين الديناميكي + - الحفاظ على مسار تدقيق كامل للامتثال المالي + + + + **حالة الاستخدام**: توجيه المراجعات إلى مالكي الحسابات من CRM + + - يجلب التدفق بريد مالك الحساب من CRM + - تخزين البريد في حالة التدفق (مثل `account_owner_email`) + - استخدام `assign_from_input` للتوجيه إلى الشخص المناسب تلقائيًا + + + + **حالة الاستخدام**: التحقق من مخرجات الذكاء الاصطناعي قبل التسليم للعميل + + - يولّد الذكاء الاصطناعي محتوى أو ردود موجهة للعميل + - يراجع فريق ضمان الجودة عبر إشعار البريد الإلكتروني + - حلقات الملاحظات تحسّن أداء الذكاء الاصطناعي بمرور الوقت + + + +## واجهة Webhooks API + +عندما تتوقف تدفقاتك للملاحظات البشرية، يمكنك تهيئة webhooks لإرسال بيانات الطلب إلى تطبيقك. يتيح هذا: + +- بناء واجهات موافقة مخصصة +- التكامل مع الأدوات الداخلية (Jira، ServiceNow، لوحات تحكم مخصصة) +- توجيه الموافقات إلى أنظمة طرف ثالث +- إشعارات تطبيقات الجوال +- أنظمة القرار المؤتمتة + + + HITL Webhook Configuration + + +### تهيئة Webhooks + + + + اذهب إلى **النشر** ← **الإعدادات** ← **الإنسان في الحلقة** + + + انقر لتوسيع تهيئة **Webhooks** + + + أدخل عنوان webhook الخاص بك (يجب أن يكون HTTPS في الإنتاج) + + + انقر على **حفظ التهيئة** للتفعيل + + + +يمكنك تهيئة webhooks متعددة. يستقبل كل webhook نشط جميع أحداث HITL. + +### أحداث Webhook + +ستستقبل نقطة النهاية طلبات HTTP POST لهذه الأحداث: + +| نوع الحدث | متى يُطلق | +|------------|----------------| +| `new_request` | يتوقف تدفق ويطلب ملاحظات بشرية | + +### حمولة Webhook + +تستقبل جميع webhooks حمولة JSON بهذا الهيكل: + +```json +{ + "event": "new_request", + "request": { + "id": "550e8400-e29b-41d4-a716-446655440000", + "flow_id": "flow_abc123", + "method_name": "review_article", + "message": "Please review this article for publication.", + "emit_options": ["approved", "rejected", "request_changes"], + "state": { + "article_id": 12345, + "author": "john@example.com", + "category": "technology" + }, + "metadata": {}, + "created_at": "2026-01-14T12:00:00Z" + }, + "deployment": { + "id": 456, + "name": "Content Review Flow", + "organization_id": 789 + }, + "callback_url": "https://api.crewai.com/...", + "assigned_to_email": "reviewer@company.com" +} +``` + +### الرد على الطلبات + +لإرسال الملاحظات، **أرسل POST إلى `callback_url`** المضمّن في حمولة webhook. + +```http +POST {callback_url} +Content-Type: application/json + +{ + "feedback": "Approved. Great article!", + "source": "my_custom_app" +} +``` + +### الأمان + + +جميع طلبات webhook موقّعة تشفيريًا باستخدام HMAC-SHA256 لضمان الأصالة ومنع التلاعب. + + +#### أمان Webhook + +- **توقيعات HMAC-SHA256**: يتضمن كل webhook توقيعًا تشفيريًا +- **أسرار لكل webhook**: لكل webhook سر توقيع فريد +- **مشفرة أثناء التخزين**: أسرار التوقيع مشفرة في قاعدة البيانات +- **التحقق من الطابع الزمني**: يمنع هجمات الإعادة + +#### ترويسات التوقيع + +يتضمن كل طلب webhook هذه الترويسات: + +| الترويسة | الوصف | +|--------|-------------| +| `X-Signature` | توقيع HMAC-SHA256: `sha256=` | +| `X-Timestamp` | الطابع الزمني Unix عند توقيع الطلب | + +#### التحقق + +تحقق بحساب: + +```python +import hmac +import hashlib + +expected = hmac.new( + signing_secret.encode(), + f"{timestamp}.{payload}".encode(), + hashlib.sha256 +).hexdigest() + +if hmac.compare_digest(expected, signature): + # توقيع صالح +``` + +### معالجة الأخطاء + +يجب أن تعيد نقطة نهاية webhook كود حالة 2xx لتأكيد الاستلام: + +| استجابتك | سلوكنا | +|---------------|--------------| +| 2xx | تم تسليم Webhook بنجاح | +| 4xx/5xx | مسجل كفشل، بدون إعادة محاولة | +| مهلة (30 ثانية) | مسجل كفشل، بدون إعادة محاولة | + +## الأمان والتحكم في الوصول المبني على الأدوار + +### الوصول إلى لوحة التحكم + +يُتحكم في وصول HITL على مستوى النشر: + +| الصلاحية | القدرة | +|------------|------------| +| `manage_human_feedback` | تهيئة إعدادات HITL، عرض جميع الطلبات | +| `respond_to_human_feedback` | الرد على الطلبات، عرض الطلبات المعيّنة | + +### تصريح استجابة البريد الإلكتروني + +للردود عبر البريد: +1. يشفّر رمز الرد البريد المصرّح به +2. يجب أن يتطابق بريد المرسل مع بريد الرمز +3. يجب ألا يكون الرمز منتهي الصلاحية (7 أيام افتراضيًا) +4. يجب أن يكون الطلب لا يزال معلقًا + +### مسار التدقيق + +يتم تسجيل جميع إجراءات HITL: +- إنشاء الطلب +- تغييرات التعيين +- إرسال الاستجابة (مع المصدر: لوحة تحكم/بريد/API) +- حالة استئناف التدفق + +## استكشاف الأخطاء وإصلاحها + +### عدم إرسال الرسائل + +1. تحقق من تفعيل "إشعارات البريد الإلكتروني" في التهيئة +2. تحقق من مطابقة قواعد التوجيه لاسم الطريقة +3. تحقق من صلاحية بريد المعيّن +4. تحقق من احتياطي منشئ النشر إذا لم تتطابق أي قواعد توجيه + +### عدم معالجة ردود البريد + +1. تحقق من عدم انتهاء صلاحية الرمز (7 أيام افتراضيًا) +2. تحقق من مطابقة بريد المرسل للبريد المعيّن +3. تأكد من أن الطلب لا يزال معلقًا (لم يتم الرد عليه بعد) + +### عدم استئناف التدفق + +1. تحقق من حالة الطلب في لوحة التحكم +2. تحقق من إمكانية الوصول إلى callback URL +3. تأكد من أن النشر لا يزال قيد التشغيل + +## أفضل الممارسات + + +**ابدأ ببساطة**: ابدأ بإشعارات البريد الإلكتروني لمنشئ النشر، ثم أضف قواعد التوجيه مع نضوج سير عملك. + + +1. **استخدم التعيين الديناميكي**: اسحب عناوين بريد المعيّنين من حالة التدفق للتوجيه المرن. + +2. **هيّئ الاستجابة التلقائية**: أعد استجابة احتياطية للمراجعات غير الحرجة لمنع تعليق التدفقات. + +3. **راقب أوقات الاستجابة**: استخدم التحليلات لتحديد الاختناقات وتحسين عملية المراجعة. + +4. **اجعل رسائل المراجعة واضحة**: اكتب رسائل واضحة وقابلة للتنفيذ في مزيّن `@human_feedback`. + +5. **اختبر تدفق البريد**: أرسل طلبات اختبار للتحقق من تسليم البريد قبل الانتقال للإنتاج. + +## الموارد ذات الصلة + + + + دليل التنفيذ لمزيّن `@human_feedback` + + + دليل خطوة بخطوة لإعداد سير عمل HITL + + + تهيئة التحكم في الوصول المبني على الأدوار لمؤسستك + + + إعداد إشعارات الأحداث في الوقت الفعلي + + diff --git a/docs/ar/enterprise/features/hallucination-guardrail.mdx b/docs/ar/enterprise/features/hallucination-guardrail.mdx new file mode 100644 index 000000000..7ab41ef84 --- /dev/null +++ b/docs/ar/enterprise/features/hallucination-guardrail.mdx @@ -0,0 +1,251 @@ +--- +title: حاجز الهلوسة +description: "منع واكتشاف هلوسات الذكاء الاصطناعي في مهام CrewAI" +icon: "shield-check" +mode: "wide" +--- + +## نظرة عامة + +حاجز الهلوسة هو ميزة مؤسسية تتحقق من المحتوى المولّد بالذكاء الاصطناعي لضمان أنه مبني على الحقائق ولا يحتوي على هلوسات. يحلل مخرجات المهام مقابل سياق مرجعي ويوفر ملاحظات مفصلة عند اكتشاف محتوى محتمل الهلوسة. + +## ما هي الهلوسات؟ + +تحدث هلوسات الذكاء الاصطناعي عندما تولّد نماذج اللغة محتوى يبدو معقولاً لكنه غير صحيح من الناحية الواقعية أو غير مدعوم بالسياق المقدم. يساعد حاجز الهلوسة في منع هذه المشكلات من خلال: + +- مقارنة المخرجات مع السياق المرجعي +- تقييم الأمانة للمادة المصدرية +- توفير ملاحظات مفصلة حول المحتوى المشكل +- دعم عتبات مخصصة لصرامة التحقق + +## الاستخدام الأساسي + +### إعداد الحاجز + +```python +from crewai.tasks.hallucination_guardrail import HallucinationGuardrail +from crewai import LLM + +# الاستخدام الأساسي - سيستخدم expected_output للمهمة كسياق +guardrail = HallucinationGuardrail( + llm=LLM(model="gpt-4o-mini") +) + +# مع سياق مرجعي صريح +context_guardrail = HallucinationGuardrail( + context="AI helps with various tasks including analysis and generation.", + llm=LLM(model="gpt-4o-mini") +) +``` + +### الإضافة إلى المهام + +```python +from crewai import Task + +# إنشاء مهمتك مع الحاجز +task = Task( + description="Write a summary about AI capabilities", + expected_output="A factual summary based on the provided context", + agent=my_agent, + guardrail=guardrail # إضافة الحاجز للتحقق من المخرجات +) +``` + +## التهيئة المتقدمة + +### التحقق بعتبة مخصصة + +للتحقق الأكثر صرامة، يمكنك تعيين عتبة أمانة مخصصة (مقياس 0-10): + +```python +# حاجز صارم يتطلب درجة أمانة عالية +strict_guardrail = HallucinationGuardrail( + context="Quantum computing uses qubits that exist in superposition states.", + llm=LLM(model="gpt-4o-mini"), + threshold=8.0 # يتطلب درجة >= 8 لاجتياز التحقق +) +``` + +### تضمين سياق استجابة الأدوات + +عندما تستخدم مهمتك أدوات، يمكنك تضمين استجابات الأدوات لتحقق أكثر دقة: + +```python +# حاجز مع سياق استجابة الأدوات +weather_guardrail = HallucinationGuardrail( + context="Current weather information for the requested location", + llm=LLM(model="gpt-4o-mini"), + tool_response="Weather API returned: Temperature 22°C, Humidity 65%, Clear skies" +) +``` + +## كيف يعمل + +### عملية التحقق + +1. **تحليل السياق**: يقارن الحاجز مخرجات المهمة مع السياق المرجعي المقدم +2. **تسجيل الأمانة**: يستخدم مقيّمًا داخليًا لتعيين درجة أمانة (0-10) +3. **تحديد الحكم**: يحدد ما إذا كان المحتوى أمينًا أو يحتوي على هلوسات +4. **التحقق من العتبة**: إذا تم تعيين عتبة مخصصة، يتحقق مقابل تلك الدرجة +5. **توليد الملاحظات**: يوفر أسبابًا مفصلة عند فشل التحقق + +### منطق التحقق + +- **الوضع الافتراضي**: يستخدم التحقق المبني على الحكم (FAITHFUL مقابل HALLUCINATED) +- **وضع العتبة**: يتطلب أن تلبي درجة الأمانة العتبة المحددة أو تتجاوزها +- **معالجة الأخطاء**: يتعامل بسلاسة مع أخطاء التقييم ويوفر ملاحظات إعلامية + +## نتائج الحاجز + +يعيد الحاجز نتائج منظمة تشير إلى حالة التحقق: + +```python +# مثال على هيكل نتيجة الحاجز +{ + "valid": False, + "feedback": "Content appears to be hallucinated (score: 4.2/10, verdict: HALLUCINATED). The output contains information not supported by the provided context." +} +``` + +### خصائص النتيجة + +- **valid**: قيمة منطقية تشير إلى ما إذا اجتازت المخرجات التحقق +- **feedback**: شرح مفصل عند فشل التحقق، يتضمن: + - درجة الأمانة + - تصنيف الحكم + - أسباب محددة للفشل + +## التكامل مع نظام المهام + +### التحقق التلقائي + +عند إضافة حاجز إلى مهمة، يتحقق تلقائيًا من المخرجات قبل اعتبار المهمة مكتملة: + +```python +# تدفق التحقق من مخرجات المهمة +task_output = agent.execute_task(task) +validation_result = guardrail(task_output) + +if validation_result.valid: + # المهمة تكتمل بنجاح + return task_output +else: + # المهمة تفشل مع ملاحظات التحقق + raise ValidationError(validation_result.feedback) +``` + +### تتبع الأحداث + +يتكامل الحاجز مع نظام أحداث CrewAI لتوفير المراقبة: + +- **بدء التحقق**: عند بدء تقييم الحاجز +- **اكتمال التحقق**: عند انتهاء التقييم بالنتائج +- **فشل التحقق**: عند حدوث أخطاء تقنية أثناء التقييم + +## أفضل الممارسات + +### إرشادات السياق + + + + أدرج جميع المعلومات الواقعية ذات الصلة التي يجب أن يبني عليها الذكاء الاصطناعي مخرجاته: + + ```python + context = """ + Company XYZ was founded in 2020 and specializes in renewable energy solutions. + They have 150 employees and generated $50M revenue in 2023. + Their main products include solar panels and wind turbines. + """ + ``` + + + + أدرج فقط المعلومات المرتبطة مباشرة بالمهمة لتجنب الارتباك: + + ```python + # جيد: سياق مركّز + context = "The current weather in New York is 18°C with light rain." + + # تجنب: معلومات غير ذات صلة + context = "The weather is 18°C. The city has 8 million people. Traffic is heavy." + ``` + + + + تأكد من أن السياق المرجعي يعكس معلومات حالية ودقيقة. + + + +### اختيار العتبة + + + + ابدأ بدون عتبات مخصصة لفهم الأداء الأساسي. + + + + - **محتوى عالي الأهمية**: استخدم عتبة 8-10 للدقة القصوى + - **محتوى عام**: استخدم عتبة 6-7 للتحقق المتوازن + - **محتوى إبداعي**: استخدم عتبة 4-5 أو التحقق الافتراضي المبني على الحكم + + + + تتبع نتائج التحقق واضبط العتبات بناءً على الإيجابيات/السلبيات الكاذبة. + + + +## اعتبارات الأداء + +### التأثير على زمن التنفيذ + +- **عبء التحقق**: يضيف كل حاجز حوالي 1-3 ثوانٍ لكل مهمة +- **كفاءة LLM**: اختر نماذج فعالة للتقييم (مثل gpt-4o-mini) + +### تحسين التكلفة + +- **اختيار النموذج**: استخدم نماذج أصغر وفعالة لتقييم الحاجز +- **حجم السياق**: اجعل السياق المرجعي موجزًا لكن شاملًا +- **التخزين المؤقت**: فكّر في تخزين نتائج التحقق مؤقتًا للمحتوى المتكرر + +## استكشاف الأخطاء وإصلاحها + + + **الأسباب المحتملة:** + - السياق مقيّد جدًا أو غير مرتبط بمخرجات المهمة + - العتبة معينة عالية جدًا لنوع المحتوى + - السياق المرجعي يحتوي على معلومات قديمة + + **الحلول:** + - مراجعة وتحديث السياق ليتطابق مع متطلبات المهمة + - خفض العتبة أو استخدام التحقق الافتراضي المبني على الحكم + - التأكد من أن السياق حالي ودقيق + + + + **الأسباب المحتملة:** + - العتبة عالية جدًا للمهام الإبداعية أو التفسيرية + - السياق لا يغطي جميع الجوانب الصالحة للمخرجات + - نموذج التقييم محافظ بشكل مفرط + + **الحلول:** + - خفض العتبة أو استخدام التحقق الافتراضي + - توسيع السياق ليشمل محتوى مقبول أوسع + - الاختبار مع نماذج تقييم مختلفة + + + + **الأسباب المحتملة:** + - مشكلات في الاتصال بالشبكة + - نموذج LLM غير متاح أو محدود المعدل + - مخرجات مهمة أو سياق غير صالح + + **الحلول:** + - التحقق من الاتصال بالشبكة وحالة خدمة LLM + - تنفيذ منطق إعادة المحاولة للأعطال المؤقتة + - التحقق من تنسيق مخرجات المهمة قبل تقييم الحاجز + + + + تواصل مع فريق الدعم للمساعدة في تهيئة حاجز الهلوسة أو استكشاف الأخطاء وإصلاحها. + diff --git a/docs/ar/enterprise/features/marketplace.mdx b/docs/ar/enterprise/features/marketplace.mdx new file mode 100644 index 000000000..e8b5b8514 --- /dev/null +++ b/docs/ar/enterprise/features/marketplace.mdx @@ -0,0 +1,45 @@ +--- +title: السوق +description: "اكتشف وثبّت وأدِر الأصول القابلة لإعادة الاستخدام لطواقم مؤسستك." +icon: "store" +mode: "wide" +--- + +## نظرة عامة + +يوفر السوق واجهة منظمة لاكتشاف عمليات التكامل والأدوات الداخلية والأصول القابلة لإعادة الاستخدام التي تسرّع تطوير الطواقم. + + + ![نظرة عامة على السوق](/images/enterprise/marketplace-overview.png) + + +## قابلية الاكتشاف + +- تصفح حسب الفئة والقدرة +- ابحث عن الأصول بالاسم أو الكلمة المفتاحية + +## التثبيت والتفعيل + +- تثبيت بنقرة واحدة للأصول المعتمدة +- تفعيل أو تعطيل لكل طاقم حسب الحاجة +- تهيئة متغيرات البيئة والنطاقات المطلوبة + + + ![التثبيت والتهيئة](/images/enterprise/marketplace-install.png) + + +يمكنك أيضاً تنزيل القوالب مباشرة من السوق بالنقر على زر `Download` لاستخدامها محلياً أو تعديلها حسب احتياجاتك. + +## ذو صلة + + + + اربط التطبيقات الخارجية وأدِر الأدوات الداخلية التي يمكن لوكلائك استخدامها. + + + انشر وثبّت الأدوات لتعزيز قدرات طواقمك. + + + خزّن وشارك وأعد استخدام تعريفات الوكلاء عبر الفرق والمشاريع. + + diff --git a/docs/ar/enterprise/features/pii-trace-redactions.mdx b/docs/ar/enterprise/features/pii-trace-redactions.mdx new file mode 100644 index 000000000..58f013224 --- /dev/null +++ b/docs/ar/enterprise/features/pii-trace-redactions.mdx @@ -0,0 +1,342 @@ +--- +title: إخفاء البيانات الشخصية في التتبعات +description: "إخفاء البيانات الحساسة تلقائياً من تتبعات تنفيذ الطواقم والتدفقات" +icon: "lock" +mode: "wide" +--- + +## نظرة عامة + +إخفاء البيانات الشخصية (PII Redaction) هو ميزة في CrewAI AMP تكتشف تلقائياً وتُقنّع معلومات التعريف الشخصية (PII) في تتبعات تنفيذ الطواقم والتدفقات. يضمن ذلك عدم كشف البيانات الحساسة مثل أرقام بطاقات الائتمان وأرقام الضمان الاجتماعي وعناوين البريد الإلكتروني والأسماء في تتبعات CrewAI AMP. يمكنك أيضاً إنشاء مُعرّفات مخصصة لحماية البيانات الخاصة بمؤسستك. + + + + إخفاء البيانات الشخصية متاح في خطة Enterprise. + يجب أن يكون إصدار النشر 1.8.0 أو أعلى. + + + + + ![نظرة عامة على إخفاء البيانات الشخصية](/images/enterprise/pii_mask_recognizer_trace_example.png) + + + +## أهمية إخفاء البيانات الشخصية + +عند تشغيل وكلاء الذكاء الاصطناعي في بيئة الإنتاج، غالباً ما تمر معلومات حساسة عبر طواقمك: + +- بيانات العملاء من تكاملات CRM +- معلومات مالية من معالجات الدفع +- تفاصيل شخصية من إرسالات النماذج +- بيانات الموظفين الداخلية + +بدون إخفاء مناسب، تظهر هذه البيانات في التتبعات، مما يجعل الامتثال للوائح مثل GDPR وHIPAA وPCI-DSS أمراً صعباً. يحل إخفاء البيانات الشخصية هذه المشكلة عن طريق إقناع البيانات الحساسة تلقائياً قبل تخزينها في التتبعات. + +## كيف يعمل + +1. **الاكتشاف** - مسح بيانات أحداث التتبع بحثاً عن أنماط PII المعروفة +2. **التصنيف** - تحديد نوع البيانات الحساسة (بطاقة ائتمان، SSN، بريد إلكتروني، إلخ.) +3. **الإقناع/الإخفاء** - استبدال البيانات الحساسة بقيم مُقنّعة بناءً على تهيئتك + +``` +Original: "Contact john.doe@company.com or call 555-123-4567" +Redacted: "Contact or call " +``` + +## تفعيل إخفاء البيانات الشخصية + + + يجب أن تكون على خطة Enterprise وأن يكون إصدار النشر 1.8.0 أو أعلى لاستخدام هذه الميزة. + + + + + في لوحة تحكم CrewAI AMP، اختر طاقمك المنشور وانتقل إلى أحد عمليات النشر/الأتمتة، ثم انتقل إلى **Settings** → **PII Protection**. + + + + فعّل **PII Redaction for Traces**. سيؤدي ذلك إلى تفعيل المسح والإخفاء التلقائي لبيانات التتبع. + + + تحتاج إلى تفعيل إخفاء البيانات الشخصية يدوياً لكل عملية نشر. + + + + ![تفعيل إخفاء البيانات الشخصية](/images/enterprise/pii_mask_recognizer_enable.png) + + + + + اختر أنواع البيانات الشخصية التي تريد اكتشافها وإخفاءها. يمكن تفعيل أو تعطيل كل كيان بشكل فردي. + + + ![تهيئة الكيانات](/images/enterprise/pii_mask_recognizer_supported_entities.png) + + + + + احفظ تهيئتك. سيكون إخفاء البيانات الشخصية نشطاً في جميع عمليات تنفيذ الطاقم اللاحقة، دون الحاجة لإعادة النشر. + + + +## أنواع الكيانات المدعومة + +يدعم CrewAI أنواع كيانات PII التالية، منظمة حسب الفئة. + +### الكيانات العالمية + +| الكيان | الوصف | مثال | +|--------|-------|------| +| `CREDIT_CARD` | أرقام بطاقات الائتمان/الخصم | "4111-1111-1111-1111" | +| `CRYPTO` | عناوين محافظ العملات الرقمية | "bc1qxy2kgd..." | +| `DATE_TIME` | التواريخ والأوقات | "January 15, 2024" | +| `EMAIL_ADDRESS` | عناوين البريد الإلكتروني | "john@example.com" | +| `IBAN_CODE` | أرقام الحسابات المصرفية الدولية | "DE89 3704 0044 0532 0130 00" | +| `IP_ADDRESS` | عناوين IPv4 وIPv6 | "192.168.1.1" | +| `LOCATION` | المواقع الجغرافية | "New York City" | +| `MEDICAL_LICENSE` | أرقام التراخيص الطبية | "MD12345" | +| `NRP` | الجنسيات أو المجموعات الدينية أو السياسية | - | +| `PERSON` | الأسماء الشخصية | "John Doe" | +| `PHONE_NUMBER` | أرقام الهواتف بتنسيقات مختلفة | "+1 (555) 123-4567" | +| `URL` | عناوين URL | "https://example.com" | + +### كيانات خاصة بالولايات المتحدة + +| الكيان | الوصف | مثال | +|--------|-------|------| +| `US_BANK_NUMBER` | أرقام الحسابات المصرفية الأمريكية | "1234567890" | +| `US_DRIVER_LICENSE` | أرقام رخص القيادة الأمريكية | "D1234567" | +| `US_ITIN` | رقم تعريف دافع الضرائب الفردي | "900-70-0000" | +| `US_PASSPORT` | أرقام جوازات السفر الأمريكية | "123456789" | +| `US_SSN` | أرقام الضمان الاجتماعي | "123-45-6789" | + +## إجراءات الإخفاء + +لكل كيان مُفعّل، يمكنك تهيئة كيفية إخفاء البيانات: + +| الإجراء | الوصف | مثال على المخرجات | +|---------|-------|-------------------| +| `mask` | الاستبدال بتسمية نوع الكيان | `` | +| `redact` | إزالة النص بالكامل | *(فارغ)* | + +## المُعرّفات المخصصة + +بالإضافة إلى الكيانات المدمجة، يمكنك إنشاء **مُعرّفات مخصصة** لاكتشاف أنماط PII الخاصة بمؤسستك. + + + ![المُعرّفات المخصصة](/images/enterprise/pii_mask_recognizer.png) + + +### أنواع المُعرّفات + +لديك خياران للمُعرّفات المخصصة: + +| النوع | الأفضل لـ | مثال على حالة الاستخدام | +|-------|-----------|------------------------| +| **قائم على النمط (Regex)** | بيانات منظمة بتنسيقات متوقعة | مبالغ الرواتب، معرّفات الموظفين، رموز المشاريع | +| **قائمة الحظر (Deny-list)** | مطابقة النصوص بالضبط | أسماء الشركات، الأسماء الرمزية الداخلية، مصطلحات محددة | + +### إنشاء مُعرّف مخصص + + + + انتقل إلى **Settings** → **Organization** → **Add Recognizer** في إعدادات مؤسستك. + + + + + ![تهيئة المُعرّف](/images/enterprise/pii_mask_recognizer_create.png) + + + هيّئ الحقول التالية: + - **Name**: اسم وصفي للمُعرّف + - **Entity Type**: تسمية الكيان التي ستظهر في المخرجات المُخفاة (مثل `EMPLOYEE_ID`، `SALARY`) + - **Type**: اختر بين Regex Pattern أو Deny List + - **Pattern/Values**: نمط Regex أو قائمة نصوص للمطابقة + - **Confidence Threshold**: الحد الأدنى للنتيجة (0.0-1.0) المطلوبة لتفعيل الإخفاء عند المطابقة. القيم الأعلى (مثل 0.8) تقلل الإيجابيات الخاطئة لكن قد تفوّت بعض المطابقات. القيم الأقل (مثل 0.5) تلتقط المزيد من المطابقات لكن قد تُفرط في الإخفاء. القيمة الافتراضية هي 0.8. + - **Context Words** (اختياري): كلمات تزيد ثقة الاكتشاف عند وجودها بالقرب + + + + احفظ المُعرّف. سيكون متاحاً للتفعيل في عمليات النشر الخاصة بك. + + + +### فهم أنواع الكيانات + +يحدد **Entity Type** كيفية ظهور المحتوى المُطابق في التتبعات المُخفاة: + +``` +Entity Type: SALARY +Pattern: salary:\s*\$\s*\d+ +Input: "Employee salary: $50,000" +Output: "Employee " +``` + +### استخدام كلمات السياق + +تحسّن كلمات السياق الدقة عن طريق زيادة الثقة عند ظهور مصطلحات محددة بالقرب من النمط المُطابق: + +``` +Context Words: "project", "code", "internal" +Entity Type: PROJECT_CODE +Pattern: PRJ-\d{4} +``` + +عندما تظهر كلمة "project" أو "code" بالقرب من "PRJ-1234"، يكون لدى المُعرّف ثقة أعلى بأنها مطابقة حقيقية، مما يقلل الإيجابيات الخاطئة. + + +## عرض التتبعات المُخفاة + +بمجرد تفعيل إخفاء البيانات الشخصية، ستعرض تتبعاتك قيماً مُخفاة بدلاً من البيانات الحساسة: + +``` +Task Output: "Customer placed order #12345. +Contact email: , phone: . +Payment processed for card ending in ." +``` + +القيم المُخفاة مُعلّمة بوضوح بأقواس زاوية وتسمية نوع الكيان (مثل ``)، مما يسهّل فهم البيانات التي تمت حمايتها مع السماح لك بتصحيح الأخطاء ومراقبة سلوك الطاقم. + + + +## أفضل الممارسات + +### اعتبارات الأداء + + + + كل كيان مُفعّل يضيف عبء معالجة. فعّل فقط الكيانات ذات الصلة ببياناتك. + + + + للمُعرّفات المخصصة، استخدم أنماطاً محددة لتقليل الإيجابيات الخاطئة وتحسين الأداء. أنماط Regex هي الأفضل عند تحديد أنماط معينة في التتبعات مثل الرواتب ومعرّفات الموظفين ورموز المشاريع وغيرها. مُعرّفات قائمة الحظر هي الأفضل عند تحديد نصوص بعينها في التتبعات مثل أسماء الشركات والأسماء الرمزية الداخلية وغيرها. + + + + تحسّن كلمات السياق الدقة عن طريق تفعيل الاكتشاف فقط عندما يتطابق النص المحيط. + + + +## استكشاف الأخطاء وإصلاحها + + + **الأسباب المحتملة:** + - نوع الكيان غير مُفعّل في التهيئة + - النمط لا يتطابق مع تنسيق البيانات + - المُعرّف المخصص يحتوي على أخطاء في الصياغة + + **الحلول:** + - تحقق من أن الكيان مُفعّل في Settings → Security + - اختبر أنماط Regex مع بيانات نموذجية + - تحقق من السجلات بحثاً عن أخطاء التهيئة + + + + **الأسباب المحتملة:** + - أنواع كيانات واسعة جداً مُفعّلة (مثل `DATE_TIME` تلتقط التواريخ في كل مكان) + - أنماط المُعرّف المخصص عامة جداً + + **الحلول:** + - عطّل الكيانات التي تسبب إيجابيات خاطئة + - اجعل الأنماط المخصصة أكثر تحديداً + - أضف كلمات سياق لتحسين الدقة + + + + **الأسباب المحتملة:** + - عدد كبير جداً من الكيانات المُفعّلة + - الكيانات القائمة على NLP (مثل `PERSON` و`LOCATION` و`NRP`) مكلفة حسابياً لأنها تستخدم نماذج تعلم الآلة + + **الحلول:** + - فعّل فقط الكيانات التي تحتاجها فعلاً + - فكّر في استخدام بدائل قائمة على الأنماط حيثما أمكن + - راقب أوقات معالجة التتبعات في لوحة التحكم + + +--- + +## مثال عملي: مطابقة نمط الراتب + +يوضح هذا المثال كيفية إنشاء مُعرّف مخصص لاكتشاف وإقناع معلومات الرواتب في تتبعاتك. + +### حالة الاستخدام + +يعالج طاقمك بيانات موظفين أو بيانات مالية تتضمن معلومات رواتب بتنسيقات مثل: +- `salary: $50,000` +- `salary: $125,000.00` +- `salary:$1,500.50` + +تريد إقناع هذه القيم تلقائياً لحماية بيانات التعويضات الحساسة. + +### التهيئة + + + ![تهيئة مُعرّف الراتب](/images/enterprise/pii_mask_custom_recognizer_salary.png) + + +| الحقل | القيمة | +|-------|--------| +| **Name** | `SALARY` | +| **Entity Type** | `SALARY` | +| **Type** | Regex Pattern | +| **Regex Pattern** | `salary:\s*\$\s*\d{1,3}(,\d{3})*(\.\d{2})?` | +| **Action** | Mask | +| **Confidence Threshold** | `0.8` | +| **Context Words** | `salary, compensation, pay, wage, income` | + +### تحليل نمط Regex + +| مكون النمط | المعنى | +|------------|--------| +| `salary:` | يطابق النص الحرفي "salary:" | +| `\s*` | يطابق صفر أو أكثر من أحرف المسافات البيضاء | +| `\$` | يطابق علامة الدولار (مُهرّبة) | +| `\s*` | يطابق صفر أو أكثر من أحرف المسافات البيضاء بعد $ | +| `\d{1,3}` | يطابق 1-3 أرقام (مثل "1"، "50"، "125") | +| `(,\d{3})*` | يطابق الآلاف المفصولة بفواصل (مثل ",000"، ",500,000") | +| `(\.\d{2})?` | يطابق اختيارياً السنتات (مثل ".00"، ".50") | + +### أمثلة على النتائج + +``` +Original: "Employee record shows salary: $125,000.00 annually" +Redacted: "Employee record shows annually" + +Original: "Base salary:$50,000 with bonus potential" +Redacted: "Base with bonus potential" +``` + + + إضافة كلمات سياق مثل "salary" و"compensation" و"pay" و"wage" و"income" تساعد في زيادة ثقة الاكتشاف عند ظهور هذه المصطلحات بالقرب من النمط المُطابق، مما يقلل الإيجابيات الخاطئة. + + +### تفعيل المُعرّف لعمليات النشر + + + إنشاء مُعرّف مخصص على مستوى المؤسسة لا يفعّله تلقائياً لعمليات النشر. يجب عليك تفعيل كل مُعرّف يدوياً لكل عملية نشر تريد تطبيقه عليها. + + +بعد إنشاء المُعرّف المخصص، فعّله لكل عملية نشر: + + + + انتقل إلى عملية النشر/الأتمتة وافتح **Settings** → **PII Protection**. + + + + تحت **Mask Recognizers**، سترى المُعرّفات المحددة على مستوى مؤسستك. حدد المربع بجانب المُعرّفات التي تريد تفعيلها. + + + ![تفعيل المُعرّف المخصص](/images/enterprise/pii_mask_recognizers_options.png) + + + + + احفظ تغييراتك. سيكون المُعرّف نشطاً في جميع عمليات التنفيذ اللاحقة لعملية النشر هذه. + + + + + كرر هذه العملية لكل عملية نشر تحتاج فيها إلى المُعرّف المخصص. يمنحك ذلك تحكماً دقيقاً في المُعرّفات النشطة في البيئات المختلفة (مثل بيئة التطوير مقابل بيئة الإنتاج). + diff --git a/docs/ar/enterprise/features/rbac.mdx b/docs/ar/enterprise/features/rbac.mdx new file mode 100644 index 000000000..166e905cc --- /dev/null +++ b/docs/ar/enterprise/features/rbac.mdx @@ -0,0 +1,256 @@ +--- +title: "التحكم في الوصول القائم على الأدوار (RBAC)" +description: "تحكم في الوصول إلى الطواقم والأدوات والبيانات باستخدام الأدوار والنطاقات والصلاحيات الدقيقة." +icon: "shield" +mode: "wide" +--- + +## نظرة عامة + +يتيح RBAC في CrewAI AMP إدارة وصول آمنة وقابلة للتوسع من خلال طبقتين: + +1. **صلاحيات الميزات** — تتحكم في ما يمكن لكل دور القيام به عبر المنصة (إدارة، قراءة، أو بدون وصول) +2. **صلاحيات على مستوى الكيان** — وصول دقيق للأتمتات الفردية ومتغيرات البيئة واتصالات LLM ومستودعات Git + + + نظرة عامة على RBAC في CrewAI AMP + + +## المستخدمون والأدوار + +يُعيَّن لكل عضو في مساحة عمل CrewAI دور يحدد صلاحيات الوصول عبر الميزات المختلفة. + +يمكنك: + +- استخدام الأدوار المحددة مسبقاً (Owner، Member) +- إنشاء أدوار مخصصة مصممة لصلاحيات محددة +- تعيين الأدوار في أي وقت عبر لوحة الإعدادات + +يمكنك تهيئة المستخدمين والأدوار في Settings → Roles. + + + + انتقل إلى Settings → Roles في CrewAI AMP. + + + استخدم دوراً محدداً مسبقاً (Owner، Member) أو انقر على{" "} + Create role لتحديد دور مخصص. + + + اختر المستخدمين وعيّن لهم الدور. يمكنك تغيير ذلك في أي وقت. + + + +### الأدوار المحددة مسبقاً + +| الدور | الوصف | +| :---------- | :-------------------------------------------------------------------- | +| **Owner** | وصول كامل لجميع الميزات والإعدادات. لا يمكن تقييده. | +| **Member** | وصول للقراءة لمعظم الميزات، وصول إدارة لمتغيرات البيئة واتصالات LLM ومشاريع Studio. لا يمكنه تعديل إعدادات المؤسسة أو الإعدادات الافتراضية. | + +### ملخص التهيئة + +| المجال | مكان التهيئة | الخيارات | +| :-------------------- | :--------------------------------- | :-------------------------------------- | +| المستخدمون والأدوار | Settings → Roles | محددة مسبقاً: Owner، Member؛ أدوار مخصصة | +| رؤية الأتمتة | Automation → Settings → Visibility | خاص؛ قائمة بيضاء للمستخدمين/الأدوار | + +--- + +## مصفوفة صلاحيات الميزات + +لكل دور مستوى صلاحية لكل منطقة ميزة. المستويات الثلاثة هي: + +- **إدارة (Manage)** — وصول كامل للقراءة/الكتابة (إنشاء، تعديل، حذف) +- **قراءة (Read)** — وصول للعرض فقط +- **بدون وصول (No access)** — الميزة مخفية/غير قابلة للوصول + +| الميزة | Owner | Member (افتراضي) | المستويات المتاحة | الوصف | +| :------------------------ | :------ | :--------------- | :--------------------------------- | :-------------------------------------------------------------- | +| `usage_dashboards` | Manage | Read | Manage / Read / No access | عرض مقاييس وتحليلات الاستخدام | +| `crews_dashboards` | Manage | Read | Manage / Read / No access | عرض لوحات النشر والوصول إلى تفاصيل الأتمتة | +| `invitations` | Manage | Read | Manage / Read / No access | دعوة أعضاء جدد إلى المؤسسة | +| `training_ui` | Manage | Read | Manage / Read / No access | الوصول إلى واجهات التدريب/الضبط الدقيق | +| `tools` | Manage | Read | Manage / Read / No access | إنشاء وإدارة الأدوات | +| `agents` | Manage | Read | Manage / Read / No access | إنشاء وإدارة الوكلاء | +| `environment_variables` | Manage | Manage | Manage / No access | إنشاء وإدارة متغيرات البيئة | +| `llm_connections` | Manage | Manage | Manage / No access | تهيئة اتصالات مزودي LLM | +| `default_settings` | Manage | No access | Manage / No access | تعديل الإعدادات الافتراضية على مستوى المؤسسة | +| `organization_settings` | Manage | No access | Manage / No access | إدارة الفوترة والخطط وتهيئة المؤسسة | +| `studio_projects` | Manage | Manage | Manage / No access | إنشاء وتعديل المشاريع في Studio | + + + عند إنشاء دور مخصص، يمكن ضبط معظم الميزات على **Manage** أو **Read** أو **No access**. ومع ذلك، فإن `environment_variables` و`llm_connections` و`default_settings` و`organization_settings` و`studio_projects` تدعم فقط **Manage** أو **No access** — لا يوجد خيار للقراءة فقط لهذه الميزات. + + +--- + +## النشر من GitHub أو Zip + +من أكثر أسئلة RBAC شيوعاً: _"ما الصلاحيات التي يحتاجها عضو الفريق للنشر؟"_ + +### النشر من GitHub + +لنشر أتمتة من مستودع GitHub، يحتاج المستخدم إلى: + +1. **`crews_dashboards`**: على الأقل `Read` — مطلوب للوصول إلى لوحة الأتمتات حيث يتم إنشاء عمليات النشر +2. **الوصول إلى مستودع Git** (إذا كان RBAC على مستوى الكيان لمستودعات Git مفعلاً): يجب منح دور المستخدم الوصول إلى مستودع Git المحدد عبر صلاحيات مستوى الكيان +3. **`studio_projects`: `Manage`** — إذا كان يبني الطاقم في Studio قبل النشر + +### النشر من Zip + +لنشر أتمتة من ملف Zip، يحتاج المستخدم إلى: + +1. **`crews_dashboards`**: على الأقل `Read` — مطلوب للوصول إلى لوحة الأتمتات +2. **تفعيل نشر Zip**: يجب ألا تكون المؤسسة قد عطلت نشر Zip في إعدادات المؤسسة + +### مرجع سريع: الحد الأدنى من الصلاحيات للنشر + +| الإجراء | صلاحيات الميزات المطلوبة | متطلبات إضافية | +| :------------------- | :----------------------------------- | :----------------------------------------------- | +| النشر من GitHub | `crews_dashboards: Read` | وصول كيان مستودع Git (إذا كان Git RBAC مفعلاً) | +| النشر من Zip | `crews_dashboards: Read` | يجب تفعيل نشر Zip على مستوى المؤسسة | +| البناء في Studio | `studio_projects: Manage` | — | +| تهيئة مفاتيح LLM | `llm_connections: Manage` | — | +| ضبط متغيرات البيئة | `environment_variables: Manage` | وصول مستوى الكيان (إذا كان RBAC الكيان مفعلاً) | + +--- + +## التحكم في الوصول على مستوى الأتمتة (صلاحيات الكيان) + +بالإضافة إلى الأدوار على مستوى المؤسسة، يدعم CrewAI صلاحيات دقيقة على مستوى الكيان تقيد الوصول إلى موارد فردية. + +### رؤية الأتمتة + +تدعم الأتمتات إعدادات رؤية تقيد الوصول حسب المستخدم أو الدور. هذا مفيد لـ: + +- الحفاظ على خصوصية الأتمتات الحساسة أو التجريبية +- إدارة الرؤية عبر الفرق الكبيرة أو المتعاونين الخارجيين +- اختبار الأتمتات في سياقات معزولة + +يمكن تهيئة عمليات النشر كخاصة، مما يعني أن المستخدمين والأدوار المدرجين في القائمة البيضاء فقط سيتمكنون من التفاعل معها. + +يمكنك تهيئة التحكم في الوصول على مستوى الأتمتة في Automation → Settings → علامة تبويب Visibility. + + + + انتقل إلى Automation → Settings → Visibility. + + + اختر Private لتقييد الوصول. يحتفظ مالك المؤسسة دائماً + بالوصول. + + + أضف مستخدمين وأدواراً محددة مسموح لهم بالعرض والتشغيل والوصول + إلى السجلات/المقاييس/الإعدادات. + + + احفظ التغييرات، ثم تأكد من أن المستخدمين غير المدرجين في القائمة البيضاء لا يمكنهم عرض أو تشغيل + الأتمتة. + + + +### الرؤية الخاصة: نتائج الوصول + +| الإجراء | المالك | مستخدم/دور في القائمة البيضاء | غير مدرج في القائمة البيضاء | +| :--------------------------- | :---- | :---------------------------- | :-------------------------- | +| عرض الأتمتة | ✓ | ✓ | ✗ | +| تشغيل الأتمتة/API | ✓ | ✓ | ✗ | +| الوصول إلى السجلات/المقاييس/الإعدادات | ✓ | ✓ | ✗ | + + + يتمتع مالك المؤسسة دائماً بالوصول. في الوضع الخاص، يمكن فقط للمستخدمين + والأدوار المدرجين في القائمة البيضاء العرض والتشغيل والوصول إلى السجلات/المقاييس/الإعدادات. + + + + إعدادات رؤية الأتمتة في CrewAI AMP + + +### أنواع صلاحيات النشر + +عند منح وصول على مستوى الكيان لأتمتة محددة، يمكنك تعيين أنواع الصلاحيات التالية: + +| الصلاحية | ما تسمح به | +| :------------------- | :-------------------------------------------------- | +| `run` | تنفيذ الأتمتة واستخدام API الخاص بها | +| `traces` | عرض تتبعات التنفيذ والسجلات | +| `manage_settings` | تعديل، إعادة نشر، استرجاع، أو حذف الأتمتة | +| `human_in_the_loop` | الرد على طلبات الإنسان في الحلقة (HITL) | +| `full_access` | جميع ما سبق | + +### RBAC على مستوى الكيان لموارد أخرى + +عند تفعيل RBAC على مستوى الكيان، يمكن أيضاً التحكم في الوصول لهذه الموارد حسب المستخدم أو الدور: + +| المورد | يتم التحكم فيه بواسطة | الوصف | +| :-------------------- | :--------------------------------- | :------------------------------------------------------------- | +| متغيرات البيئة | علامة ميزة RBAC الكيان | تقييد أي الأدوار/المستخدمين يمكنهم عرض أو إدارة متغيرات بيئة محددة | +| اتصالات LLM | علامة ميزة RBAC الكيان | تقييد الوصول لتهيئات مزودي LLM محددة | +| مستودعات Git | إعداد RBAC لمستودعات Git بالمؤسسة | تقييد أي الأدوار/المستخدمين يمكنهم الوصول لمستودعات متصلة محددة | + +--- + +## أنماط الأدوار الشائعة + +بينما يأتي CrewAI بدوري Owner وMember، تستفيد معظم الفرق من إنشاء أدوار مخصصة. إليك الأنماط الشائعة: + +### دور المطور + +دور لأعضاء الفريق الذين يبنون وينشرون الأتمتات لكن لا يديرون إعدادات المؤسسة. + +| الميزة | الصلاحية | +| :------------------------ | :---------- | +| `usage_dashboards` | Read | +| `crews_dashboards` | Manage | +| `invitations` | Read | +| `training_ui` | Read | +| `tools` | Manage | +| `agents` | Manage | +| `environment_variables` | Manage | +| `llm_connections` | Manage | +| `default_settings` | No access | +| `organization_settings` | No access | +| `studio_projects` | Manage | + +### دور المشاهد / أصحاب المصلحة + +دور للمعنيين غير التقنيين الذين يحتاجون لمراقبة الأتمتات وعرض النتائج. + +| الميزة | الصلاحية | +| :------------------------ | :---------- | +| `usage_dashboards` | Read | +| `crews_dashboards` | Read | +| `invitations` | No access | +| `training_ui` | Read | +| `tools` | Read | +| `agents` | Read | +| `environment_variables` | No access | +| `llm_connections` | No access | +| `default_settings` | No access | +| `organization_settings` | No access | +| `studio_projects` | No access | + +### دور مسؤول العمليات / المنصة + +دور لمشغلي المنصة الذين يديرون إعدادات البنية التحتية لكن قد لا يبنون الوكلاء. + +| الميزة | الصلاحية | +| :------------------------ | :---------- | +| `usage_dashboards` | Manage | +| `crews_dashboards` | Manage | +| `invitations` | Manage | +| `training_ui` | Read | +| `tools` | Read | +| `agents` | Read | +| `environment_variables` | Manage | +| `llm_connections` | Manage | +| `default_settings` | Manage | +| `organization_settings` | Read | +| `studio_projects` | No access | + +--- + + + تواصل مع فريق الدعم للمساعدة في أسئلة RBAC. + diff --git a/docs/ar/enterprise/features/tools-and-integrations.mdx b/docs/ar/enterprise/features/tools-and-integrations.mdx new file mode 100644 index 000000000..146523f26 --- /dev/null +++ b/docs/ar/enterprise/features/tools-and-integrations.mdx @@ -0,0 +1,261 @@ +--- +title: الأدوات والتكاملات +description: "اربط التطبيقات الخارجية وأدِر الأدوات الداخلية التي يمكن لوكلائك استخدامها." +icon: "wrench" +mode: "wide" +--- + +## نظرة عامة + +الأدوات والتكاملات هي المركز الرئيسي لربط تطبيقات الجهات الخارجية وإدارة الأدوات الداخلية التي يمكن لوكلائك استخدامها أثناء التشغيل. + + + ![نظرة عامة على الأدوات والتكاملات](/images/enterprise/crew_connectors.png) + + +## استكشاف + + + + +## تطبيقات الوكلاء (التكاملات) + +اربط تطبيقات المؤسسات (مثل Gmail وGoogle Drive وHubSpot وSlack) عبر OAuth لتمكين إجراءات الوكلاء. + +{" "} + + + انقر على Connect في أحد التطبيقات وأكمل عملية OAuth. + + + عدّل اختيارياً النطاقات والمشغلات وتوفر الإجراءات. + + + تصبح الخدمات المتصلة متاحة كأدوات لوكلائك. + + + +{" "} +![شبكة التكاملات](/images/enterprise/agent-apps.png) + +### ربط حسابك + +1. انتقل إلى Integrations +2. انقر على Connect في الخدمة المطلوبة +3. أكمل تدفق OAuth وامنح النطاقات +4. انسخ رمز Enterprise من Integration Settings + +{" "} + + ![رمز Enterprise](/images/enterprise/enterprise_action_auth_token.png) + + +### تثبيت أدوات التكامل + +لاستخدام التكاملات محلياً، تحتاج إلى تثبيت أحدث حزمة `crewai-tools`. + +```bash +uv add crewai-tools +``` + +### إعداد متغيرات البيئة + +{" "} + + لاستخدام التكاملات مع `Agent(apps=[])` يجب تعيين متغير البيئة + `CREWAI_PLATFORM_INTEGRATION_TOKEN` برمز Enterprise الخاص بك. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +أو أضفه إلى ملف `.env`: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +### مثال على الاستخدام + +{" "} + + استخدم النهج المبسط الجديد لدمج تطبيقات المؤسسات. ما عليك سوى تحديد + التطبيق وإجراءاته مباشرة في تهيئة Agent. + + +```python +from crewai import Agent, Task, Crew + +# Create an agent with Gmail capabilities +email_agent = Agent( + role="Email Manager", + goal="Manage and organize email communications", + backstory="An AI assistant specialized in email management and communication.", + apps=['gmail', 'gmail/send_email'] # Using canonical name 'gmail' +) + +# Task to send an email +email_task = Task( + description="Draft and send a follow-up email to john@example.com about the project update", + agent=email_agent, + expected_output="Confirmation that email was sent successfully" +) + +# Run the task +crew = Crew( + agents=[email_agent], + tasks=[email_task] +) + +# Run the crew +crew.kickoff() +``` + +### تصفية الأدوات + +```python +from crewai import Agent, Task, Crew + +# Create agent with specific Gmail actions only +gmail_agent = Agent( + role="Gmail Manager", + goal="Manage gmail communications and notifications", + backstory="An AI assistant that helps coordinate gmail communications.", + apps=['gmail/fetch_emails'] # Using canonical name with specific action +) + +notification_task = Task( + description="Find the email from john@example.com", + agent=gmail_agent, + expected_output="Email found from john@example.com" +) + +crew = Crew( + agents=[gmail_agent], + tasks=[notification_task] +) +``` + +في الطاقم المنشور، يمكنك تحديد الإجراءات المتاحة لكل تكامل من صفحة إعدادات الخدمة. + +{" "} + + ![تصفية الإجراءات](/images/enterprise/filtering_enterprise_action_tools.png) + + +### عمليات النشر المحددة النطاق (مؤسسات متعددة المستخدمين) + +يمكنك تحديد نطاق كل تكامل لمستخدم معين. على سبيل المثال، طاقم يتصل بـ Google يمكنه استخدام حساب Gmail لمستخدم محدد. + +{" "} +مفيد عندما تحتاج فرق/مستخدمون مختلفون للحفاظ على فصل الوصول إلى البيانات. + +استخدم `user_bearer_token` لتحديد نطاق المصادقة للمستخدم الطالب. إذا لم يكن المستخدم مسجل الدخول، فلن يستخدم الطاقم التكاملات المتصلة. وإلا فسيعود إلى رمز الحامل الافتراضي المهيأ لعملية النشر. + +{" "} +![رمز حامل المستخدم](/images/enterprise/user_bearer_token.png) + +{" "} +
+### الكتالوج + +#### الاتصالات والتعاون + +- Gmail — إدارة الرسائل الإلكترونية والمسودات +- Slack — إشعارات وتنبيهات مساحة العمل +- Microsoft — تكامل Office 365 وTeams + +#### إدارة المشاريع + +- Jira — تتبع المشكلات وإدارة المشاريع +- ClickUp — إدارة المهام والإنتاجية +- Asana — تنسيق مهام ومشاريع الفريق +- Notion — إدارة الصفحات وقواعد البيانات +- Linear — تتبع مشاريع البرمجيات والأخطاء +- GitHub — إدارة المستودعات والمشكلات + +#### إدارة علاقات العملاء + +- Salesforce — إدارة حسابات وفرص CRM +- HubSpot — إدارة خط أنابيب المبيعات وجهات الاتصال +- Zendesk — إدارة تذاكر دعم العملاء + +#### الأعمال والمالية + +- Stripe — معالجة المدفوعات وإدارة العملاء +- Shopify — إدارة متجر ومنتجات التجارة الإلكترونية + +#### الإنتاجية والتخزين + +- Google Sheets — مزامنة بيانات جداول البيانات +- Google Calendar — إدارة الأحداث والجداول +- Box — تخزين الملفات وإدارة المستندات + +...والمزيد قادم! + + + + +## الأدوات الداخلية + +أنشئ أدوات مخصصة محلياً، وانشرها في مستودع أدوات CrewAI AMP واستخدمها في وكلائك. + +{" "} + + قبل تشغيل الأوامر أدناه، تأكد من تسجيل الدخول إلى حساب CrewAI AMP + بتشغيل هذا الأمر: ```bash crewai login ``` + + +{" "} + + ![تفاصيل الأداة الداخلية](/images/enterprise/tools-integrations-internal.png) + + +{" "} + + + أنشئ أداة جديدة محلياً. ```bash crewai tool create your-tool ``` + + + انشر الأداة في مستودع أدوات CrewAI AMP. ```bash crewai tool + publish ``` + + + ثبّت الأداة من مستودع أدوات CrewAI AMP. ```bash crewai tool + install your-tool ``` + + + +الإدارة: + +- الاسم والوصف +- الرؤية (خاص / عام) +- متغيرات البيئة المطلوبة +- سجل الإصدارات والتنزيلات +- وصول الفرق والأدوار + +{" "} +![تفاصيل الأداة الداخلية](/images/enterprise/tool-configs.png) + + + + +## ذو صلة + + + + أنشئ وانشر وأدِر إصدارات الأدوات المخصصة لمؤسستك. + + + أتمت سير العمل وتكامل مع المنصات والخدمات الخارجية. + + diff --git a/docs/ar/enterprise/features/traces.mdx b/docs/ar/enterprise/features/traces.mdx new file mode 100644 index 000000000..533faae25 --- /dev/null +++ b/docs/ar/enterprise/features/traces.mdx @@ -0,0 +1,148 @@ +--- +title: التتبعات +description: "استخدام التتبعات لمراقبة طواقمك" +icon: "timeline" +mode: "wide" +--- + +## نظرة عامة + +توفر التتبعات رؤية شاملة لعمليات تنفيذ طواقمك، مما يساعدك على مراقبة الأداء وتصحيح الأخطاء وتحسين سير عمل وكلاء الذكاء الاصطناعي. + +## ما هي التتبعات؟ + +التتبعات في CrewAI AMP هي سجلات تنفيذ مفصلة تلتقط كل جانب من جوانب عمل طاقمك، من المدخلات الأولية إلى المخرجات النهائية. تسجل: + +- أفكار الوكلاء واستدلالاتهم +- تفاصيل تنفيذ المهام +- استخدام الأدوات ومخرجاتها +- مقاييس استهلاك الرموز +- أوقات التنفيذ +- تقديرات التكلفة + +![نظرة عامة على التتبعات](/images/enterprise/traces-overview.png) + +## الوصول إلى التتبعات + + + + في لوحة تحكم CrewAI AMP، انقر على **Traces** لعرض جميع سجلات التنفيذ. + + + + سترى قائمة بجميع عمليات تنفيذ الطاقم، مرتبة حسب التاريخ. انقر على أي عملية تنفيذ لعرض تتبعها المفصل. + + + +## فهم واجهة التتبع + +تنقسم واجهة التتبع إلى عدة أقسام، يقدم كل منها رؤى مختلفة حول تنفيذ طاقمك: + +### 1. ملخص التنفيذ + +يعرض القسم العلوي مقاييس عالية المستوى حول التنفيذ: + +- **إجمالي الرموز**: عدد الرموز المستهلكة عبر جميع المهام +- **رموز الطلب**: الرموز المستخدمة في الطلبات إلى LLM +- **رموز الإكمال**: الرموز المُنشأة في استجابات LLM +- **الطلبات**: عدد استدعاءات API المُجراة +- **وقت التنفيذ**: المدة الإجمالية لتشغيل الطاقم +- **التكلفة المقدرة**: التكلفة التقريبية بناءً على استخدام الرموز + +![ملخص التنفيذ](/images/enterprise/trace-summary.png) + +### 2. المهام والوكلاء + +يعرض هذا القسم جميع المهام والوكلاء الذين كانوا جزءاً من تنفيذ الطاقم: + +- اسم المهمة وتعيين الوكيل +- الوكلاء ونماذج LLM المستخدمة لكل مهمة +- الحالة (مكتملة/فاشلة) +- وقت التنفيذ الفردي للمهمة + +![قائمة المهام](/images/enterprise/trace-tasks.png) + +### 3. المخرجات النهائية + +يعرض النتيجة النهائية التي أنتجها الطاقم بعد اكتمال جميع المهام. + +![المخرجات النهائية](/images/enterprise/final-output.png) + +### 4. الجدول الزمني للتنفيذ + +تمثيل مرئي لوقت بدء وانتهاء كل مهمة، يساعدك على تحديد نقاط الاختناق أو أنماط التنفيذ المتوازي. + +![الجدول الزمني للتنفيذ](/images/enterprise/trace-timeline.png) + +### 5. عرض المهمة المفصل + +عند النقر على مهمة محددة في الجدول الزمني أو قائمة المهام، سترى: + +![عرض المهمة المفصل](/images/enterprise/trace-detailed-task.png) + +- **مفتاح المهمة**: معرّف فريد للمهمة +- **معرّف المهمة**: معرّف تقني في النظام +- **الحالة**: الحالة الحالية (مكتملة/قيد التشغيل/فاشلة) +- **الوكيل**: الوكيل الذي نفّذ المهمة +- **LLM**: نموذج اللغة المستخدم لهذه المهمة +- **وقت البدء/الانتهاء**: متى بدأت المهمة واكتملت +- **وقت التنفيذ**: مدة هذه المهمة المحددة +- **وصف المهمة**: ما طُلب من الوكيل تنفيذه +- **المخرجات المتوقعة**: تنسيق المخرجات المطلوب +- **المدخلات**: أي مدخلات مقدمة لهذه المهمة من مهام سابقة +- **المخرجات**: النتيجة الفعلية التي أنتجها الوكيل + +## استخدام التتبعات لتصحيح الأخطاء + +التتبعات لا تقدر بثمن لاستكشاف المشكلات في طواقمك: + + + + عندما لا ينتج تنفيذ الطاقم النتائج المتوقعة، افحص التتبع لمعرفة أين حدث الخطأ. ابحث عن: + + - المهام الفاشلة + - قرارات الوكيل غير المتوقعة + - أخطاء استخدام الأدوات + - التعليمات المُساء فهمها + + + ![نقاط الفشل](/images/enterprise/failure.png) + + + + + + استخدم مقاييس التنفيذ لتحديد نقاط اختناق الأداء: + + - المهام التي استغرقت وقتاً أطول من المتوقع + - الاستخدام المفرط للرموز + - عمليات الأدوات المكررة + - استدعاءات API غير الضرورية + + + + + حلل استخدام الرموز وتقديرات التكلفة لتحسين كفاءة طاقمك: + + - فكّر في استخدام نماذج أصغر للمهام الأبسط + - صقل الطلبات لتكون أكثر إيجازاً + - خزّن المعلومات المُوصول إليها بشكل متكرر مؤقتاً + - نظّم المهام لتقليل العمليات المكررة + + + + +## الأداء والتجميع + +يجمّع CrewAI تحميلات التتبع لتقليل العبء في عمليات التشغيل ذات الحجم الكبير: + +- يقوم TraceBatchManager بتخزين الأحداث مؤقتاً وإرسالها في دفعات عبر عميل Plus API +- يقلل حركة الشبكة ويحسّن الموثوقية في الاتصالات غير المستقرة +- يُفعّل تلقائياً في مستمع التتبع الافتراضي؛ لا حاجة لتهيئة + +يوفر ذلك تتبعاً أكثر استقراراً تحت الحمل مع الحفاظ على بيانات القياس المفصلة للمهام/الوكلاء. + + + تواصل مع فريق الدعم للمساعدة في تحليل التتبعات أو أي ميزات أخرى في + CrewAI AMP. + diff --git a/docs/ar/enterprise/features/webhook-streaming.mdx b/docs/ar/enterprise/features/webhook-streaming.mdx new file mode 100644 index 000000000..562fe0842 --- /dev/null +++ b/docs/ar/enterprise/features/webhook-streaming.mdx @@ -0,0 +1,172 @@ +--- +title: بث Webhook +description: "استخدام بث Webhook لإرسال الأحداث إلى webhook الخاص بك" +icon: "webhook" +mode: "wide" +--- + +## نظرة عامة + +يتيح لك بث أحداث Enterprise تلقي تحديثات webhook في الوقت الفعلي حول طواقمك وتدفقاتك المنشورة على CrewAI AMP، مثل استدعاءات النماذج واستخدام الأدوات وخطوات التدفق. + +## الاستخدام + +عند استخدام Kickoff API، أضف كائن `webhooks` إلى طلبك، على سبيل المثال: + +```json +{ + "inputs": { "foo": "bar" }, + "webhooks": { + "events": ["crew_kickoff_started", "llm_call_started"], + "url": "https://your.endpoint/webhook", + "realtime": false, + "authentication": { + "strategy": "bearer", + "token": "my-secret-token" + } + } +} +``` + +إذا تم تعيين `realtime` إلى `true`، يتم تسليم كل حدث بشكل فردي وفوري، على حساب أداء الطاقم/التدفق. + +## تنسيق Webhook + +يرسل كل webhook قائمة بالأحداث: + +```json +{ + "events": [ + { + "id": "event-id", + "execution_id": "crew-run-id", + "timestamp": "2025-02-16T10:58:44.965Z", + "type": "llm_call_started", + "data": { + "model": "gpt-4", + "messages": [ + { "role": "system", "content": "You are an assistant." }, + { "role": "user", "content": "Summarize this article." } + ] + } + } + ] +} +``` + +يختلف هيكل كائن `data` حسب نوع الحدث. راجع [قائمة الأحداث](https://github.com/crewAIInc/crewAI/tree/main/lib/crewai/src/crewai/events/types) على GitHub. + +نظراً لأن الطلبات تُرسل عبر HTTP، لا يمكن ضمان ترتيب الأحداث. إذا كنت تحتاج الترتيب، استخدم حقل `timestamp`. + +## الأحداث المدعومة + +يدعم CrewAI كلاً من أحداث النظام والأحداث المخصصة في بث أحداث Enterprise. تُرسل هذه الأحداث إلى نقطة نهاية webhook المُهيأة أثناء تنفيذ الطاقم والتدفق. + +### أحداث التدفق: + +- `flow_created` +- `flow_started` +- `flow_finished` +- `flow_plot` +- `method_execution_started` +- `method_execution_finished` +- `method_execution_failed` + +### أحداث الوكيل: + +- `agent_execution_started` +- `agent_execution_completed` +- `agent_execution_error` +- `lite_agent_execution_started` +- `lite_agent_execution_completed` +- `lite_agent_execution_error` +- `agent_logs_started` +- `agent_logs_execution` +- `agent_evaluation_started` +- `agent_evaluation_completed` +- `agent_evaluation_failed` + +### أحداث الطاقم: + +- `crew_kickoff_started` +- `crew_kickoff_completed` +- `crew_kickoff_failed` +- `crew_train_started` +- `crew_train_completed` +- `crew_train_failed` +- `crew_test_started` +- `crew_test_completed` +- `crew_test_failed` +- `crew_test_result` + +### أحداث المهام: + +- `task_started` +- `task_completed` +- `task_failed` +- `task_evaluation` + +### أحداث استخدام الأدوات: + +- `tool_usage_started` +- `tool_usage_finished` +- `tool_usage_error` +- `tool_validate_input_error` +- `tool_selection_error` +- `tool_execution_error` + +### أحداث LLM: + +- `llm_call_started` +- `llm_call_completed` +- `llm_call_failed` +- `llm_stream_chunk` + +### أحداث حواجز LLM: + +- `llm_guardrail_started` +- `llm_guardrail_completed` + +### أحداث الذاكرة: + +- `memory_query_started` +- `memory_query_completed` +- `memory_query_failed` +- `memory_save_started` +- `memory_save_completed` +- `memory_save_failed` +- `memory_retrieval_started` +- `memory_retrieval_completed` + +### أحداث المعرفة: + +- `knowledge_search_query_started` +- `knowledge_search_query_completed` +- `knowledge_search_query_failed` +- `knowledge_query_started` +- `knowledge_query_completed` +- `knowledge_query_failed` + +### أحداث الاستدلال: + +- `agent_reasoning_started` +- `agent_reasoning_completed` +- `agent_reasoning_failed` + +تتطابق أسماء الأحداث مع ناقل الأحداث الداخلي. راجع GitHub للقائمة الكاملة للأحداث. + +يمكنك إصدار أحداثك المخصصة الخاصة، وسيتم تسليمها عبر تدفق webhook جنباً إلى جنب مع أحداث النظام. + + + + القائمة الكاملة للأحداث + + + تواصل مع فريق الدعم للمساعدة في تكامل webhook أو + استكشاف الأخطاء. + + diff --git a/docs/ar/enterprise/guides/automation-triggers.mdx b/docs/ar/enterprise/guides/automation-triggers.mdx new file mode 100644 index 000000000..672a31814 --- /dev/null +++ b/docs/ar/enterprise/guides/automation-triggers.mdx @@ -0,0 +1,321 @@ +--- +title: "نظرة عامة على المشغلات" +description: "فهم كيفية عمل مشغلات CrewAI AMP وكيفية إدارتها وأين تجد أدلة التكامل الخاصة بكل خدمة" +icon: "face-smile" +mode: "wide" +--- + +تربط مشغلات CrewAI AMP أتمتاتك بالأحداث الفورية عبر الأدوات التي تستخدمها فرقك بالفعل. بدلاً من الاستعلام المتكرر عن الأنظمة أو الاعتماد على التشغيل اليدوي، تستمع المشغلات للتغييرات — رسائل بريد إلكتروني جديدة، تحديثات التقويم، تغييرات حالة CRM — وتطلق فوراً الطاقم أو التدفق الذي تحدده. + + + ![نظرة عامة على مشغلات الأتمتة](/images/enterprise/crew_connectors.png) + + +### أدلة التكامل + +تقدم الأدلة المفصلة شرحاً لعملية الإعداد وأمثلة على سير العمل لكل تكامل: + + + + فعّل الطواقم عند وصول رسائل بريد إلكتروني أو تحديث سلاسل المحادثات. + + +{" "} + + + استجب لأحداث التقويم عند إنشائها أو تحديثها أو إلغائها. + + + +{" "} + + + تعامل مع تحميلات وتعديلات وحذف ملفات Drive. + + + +{" "} + + + أتمت الاستجابات لرسائل Outlook الجديدة وتحديثات التقويم. + + + +{" "} + + + راقب نشاط الملفات وتغييرات المشاركة في OneDrive. + + + +{" "} + + + ابدأ سير العمل عند إنشاء محادثات Teams جديدة. + + + +{" "} + + + أطلق الأتمتات من سير عمل HubSpot وأحداث دورة الحياة. + + + +{" "} + + + اربط عمليات Salesforce بـ CrewAI لأتمتة CRM. + + + +{" "} + + + ابدأ الطواقم مباشرة من أوامر Slack. + + + + + اربط CrewAI بآلاف التطبيقات المدعومة من Zapier. + + + +## قدرات المشغلات + +مع المشغلات، يمكنك: + +- **الاستجابة للأحداث الفورية** - تنفيذ سير العمل تلقائياً عند استيفاء شروط محددة +- **التكامل مع الأنظمة الخارجية** - الاتصال بمنصات مثل Gmail وOutlook وOneDrive وJIRA وSlack وStripe والمزيد +- **توسيع نطاق الأتمتة** - التعامل مع أحداث كبيرة الحجم دون تدخل يدوي +- **الحفاظ على السياق** - الوصول إلى بيانات المشغل داخل طواقمك وتدفقاتك + +## إدارة المشغلات + +### عرض المشغلات المتاحة + +للوصول إلى مشغلات الأتمتة وإدارتها: + +1. انتقل إلى عملية النشر في لوحة تحكم CrewAI +2. انقر على علامة تبويب **Triggers** لعرض جميع تكاملات المشغلات المتاحة + + + قائمة مشغلات الأتمتة المتاحة + + +يعرض هذا العرض جميع تكاملات المشغلات المتاحة لعملية النشر، مع حالة الاتصال الحالية. + +### تفعيل وتعطيل المشغلات + +يمكن تفعيل أو تعطيل كل مشغل بسهولة باستخدام مفتاح التبديل: + + + تفعيل أو تعطيل المشغلات بالتبديل + + +- **مُفعّل (تبديل أزرق)**: المشغل نشط وسينفذ عملية النشر تلقائياً عند حدوث الأحداث المحددة +- **مُعطّل (تبديل رمادي)**: المشغل غير نشط ولن يستجيب للأحداث + +انقر ببساطة على التبديل لتغيير حالة المشغل. تسري التغييرات فوراً. + +### مراقبة عمليات تنفيذ المشغلات + +تتبع أداء وسجل عمليات التنفيذ المُشغّلة: + + + قائمة عمليات التنفيذ المُشغّلة بواسطة الأتمتة + + +## بناء أتمتات مدفوعة بالمشغلات + +قبل بناء أتمتتك، من المفيد فهم هيكل حمولات المشغلات التي ستتلقاها طواقمك وتدفقاتك. + +### قائمة فحص إعداد المشغل + +قبل ربط مشغل بالإنتاج، تأكد من: + +- ربط التكامل تحت **Tools & Integrations** وإكمال خطوات OAuth أو مفتاح API +- تفعيل تبديل المشغل في عملية النشر التي يجب أن تستجيب للأحداث +- توفير متغيرات البيئة المطلوبة (رموز API، معرّفات المستأجر، الأسرار المشتركة) +- إنشاء أو تحديث المهام التي يمكنها تحليل الحمولة الواردة في أول مهمة طاقم أو خطوة تدفق +- تحديد ما إذا كنت ستمرر سياق المشغل تلقائياً باستخدام `allow_crewai_trigger_context` +- إعداد المراقبة — سجلات webhook وسجل تنفيذ CrewAI والتنبيهات الخارجية الاختيارية + +### اختبار المشغلات محلياً باستخدام CLI + +يوفر CrewAI CLI أوامر قوية لمساعدتك في تطوير واختبار الأتمتات المدفوعة بالمشغلات دون النشر في الإنتاج. + +#### عرض المشغلات المتاحة + +اعرض جميع المشغلات المتاحة للتكاملات المتصلة: + +```bash +crewai triggers list +``` + +يعرض هذا الأمر جميع المشغلات المتاحة بناءً على تكاملاتك المتصلة، ويظهر: + +- اسم التكامل وحالة الاتصال +- أنواع المشغلات المتاحة +- أسماء وأوصاف المشغلات + +#### محاكاة تنفيذ المشغل + +اختبر طاقمك بحمولات مشغل واقعية قبل النشر: + +```bash +crewai triggers run +``` + +على سبيل المثال: + +```bash +crewai triggers run microsoft_onedrive/file_changed +``` + +يقوم هذا الأمر بـ: + +- تنفيذ طاقمك محلياً +- تمرير حمولة مشغل كاملة وواقعية +- محاكاة كيفية استدعاء طاقمك في الإنتاج بالضبط + + + **ملاحظات تطوير مهمة:** + - استخدم `crewai triggers run ` لمحاكاة تنفيذ المشغل أثناء التطوير + - استخدام `crewai run` لن يحاكي استدعاءات المشغل ولن يمرر حمولة المشغل + - بعد النشر، سيتم تنفيذ طاقمك بحمولة المشغل الفعلية + - إذا كان طاقمك يتوقع معاملات غير موجودة في حمولة المشغل، فقد يفشل التنفيذ + + +### المشغلات مع الطاقم + +تعمل تعريفات طاقمك الحالية بسلاسة مع المشغلات، تحتاج فقط إلى مهمة لتحليل الحمولة المستلمة: + +```python +@CrewBase +class MyAutomatedCrew: + @agent + def researcher(self) -> Agent: + return Agent( + config=self.agents_config['researcher'], + ) + + @task + def parse_trigger_payload(self) -> Task: + return Task( + config=self.tasks_config['parse_trigger_payload'], + agent=self.researcher(), + ) + + @task + def analyze_trigger_content(self) -> Task: + return Task( + config=self.tasks_config['analyze_trigger_data'], + agent=self.researcher(), + ) +``` + +سيتلقى الطاقم تلقائياً حمولة المشغل ويمكنه الوصول إليها عبر آليات سياق CrewAI القياسية. + + + يمكن أن تتضمن مدخلات الطاقم والتدفق `crewai_trigger_payload`. يحقن CrewAI + هذه الحمولة تلقائياً: - المهام: تُلحق بوصف المهمة الأولى افتراضياً ("Trigger Payload: {crewai_trigger_payload}") - التحكم + عبر `allow_crewai_trigger_context`: عيّن `True` للحقن دائماً، `False` لعدم + الحقن أبداً - التدفقات: أي دالة `@start()` تقبل معامل + `crewai_trigger_payload` ستستلمه + + +### التكامل مع التدفقات + +للتدفقات، لديك تحكم أكبر في كيفية التعامل مع بيانات المشغل: + +#### الوصول إلى حمولة المشغل + +جميع دوال `@start()` في تدفقاتك ستقبل معاملاً إضافياً يسمى `crewai_trigger_payload`: + +```python +from crewai.flow import Flow, start, listen + +class MyAutomatedFlow(Flow): + @start() + def handle_trigger(self, crewai_trigger_payload: dict = None): + """ + This start method can receive trigger data + """ + if crewai_trigger_payload: + # Process the trigger data + trigger_id = crewai_trigger_payload.get('id') + event_data = crewai_trigger_payload.get('payload', {}) + + # Store in flow state for use by other methods + self.state.trigger_id = trigger_id + self.state.trigger_type = event_data + + return event_data + + # Handle manual execution + return None + + @listen(handle_trigger) + def process_data(self, trigger_data): + """ + Process the data from the trigger + """ + # ... process the trigger +``` + +#### تشغيل الطواقم من التدفقات + +عند تشغيل طاقم داخل تدفق تم تشغيله بمشغل، مرر حمولة المشغل كما هي: + +```python +@start() +def delegate_to_crew(self, crewai_trigger_payload: dict = None): + """ + Delegate processing to a specialized crew + """ + crew = MySpecializedCrew() + + # Pass the trigger payload to the crew + result = crew.crew().kickoff( + inputs={ + 'a_custom_parameter': "custom_value", + 'crewai_trigger_payload': crewai_trigger_payload + }, + ) + + return result +``` + +## استكشاف الأخطاء وإصلاحها + +**المشغل لا يعمل:** + +- تحقق من أن المشغل مُفعّل في علامة تبويب Triggers الخاصة بعملية النشر +- تحقق من حالة اتصال التكامل تحت Tools & Integrations +- تأكد من تهيئة جميع متغيرات البيئة المطلوبة بشكل صحيح + +**فشل التنفيذ:** + +- تحقق من سجلات التنفيذ لتفاصيل الأخطاء +- استخدم `crewai triggers run ` للاختبار محلياً ورؤية هيكل الحمولة بالضبط +- تحقق من أن طاقمك يمكنه التعامل مع معامل `crewai_trigger_payload` +- تأكد من أن طاقمك لا يتوقع معاملات غير مضمنة في حمولة المشغل + +**مشاكل التطوير:** + +- اختبر دائماً باستخدام `crewai triggers run ` قبل النشر لرؤية الحمولة الكاملة +- تذكر أن `crewai run` لا يحاكي استدعاءات المشغل — استخدم `crewai triggers run` بدلاً من ذلك +- استخدم `crewai triggers list` للتحقق من المشغلات المتاحة لتكاملاتك المتصلة +- بعد النشر، سيتلقى طاقمك حمولة المشغل الفعلية، لذا اختبر بدقة محلياً أولاً + +تحوّل مشغلات الأتمتة عمليات نشر CrewAI إلى أنظمة استجابة مدفوعة بالأحداث يمكنها التكامل بسلاسة مع عمليات عملك وأدواتك الحالية. diff --git a/docs/ar/enterprise/guides/azure-openai-setup.mdx b/docs/ar/enterprise/guides/azure-openai-setup.mdx new file mode 100644 index 000000000..5bc23a120 --- /dev/null +++ b/docs/ar/enterprise/guides/azure-openai-setup.mdx @@ -0,0 +1,54 @@ +--- +title: "إعداد Azure OpenAI" +description: "تهيئة Azure OpenAI مع Crew Studio لاتصالات LLM المؤسسية" +icon: "microsoft" +mode: "wide" +--- + +يرشدك هذا الدليل خلال ربط Azure OpenAI مع Crew Studio لعمليات الذكاء الاصطناعي المؤسسية السلسة. + +## عملية الإعداد + + + + 1. في Azure، انتقل إلى [Azure AI Foundry](https://ai.azure.com/) > اختر نشر Azure OpenAI الخاص بك. + 2. في القائمة اليسرى، انقر على `Deployments`. إذا لم يكن لديك نشر، أنشئ واحداً بالنموذج المطلوب. + 3. بمجرد الإنشاء، اختر النشر وحدد موقع `Target URI` و`Key` على الجانب الأيمن من الصفحة. أبقِ هذه الصفحة مفتوحة، حيث ستحتاج هذه المعلومات. + + Azure AI Foundry + + + + + 4. في علامة تبويب أخرى، افتح `CrewAI AMP > LLM Connections`. سمِّ اتصال LLM، واختر Azure كمزود، واختر نفس النموذج الذي اخترته في Azure. + 5. في نفس الصفحة، أضف متغيرات البيئة من الخطوة 3: + - واحد بالاسم `AZURE_DEPLOYMENT_TARGET_URL` (باستخدام Target URI). يجب أن يبدو الرابط هكذا: https://your-deployment.openai.azure.com/openai/deployments/gpt-4o/chat/completions?api-version=2024-08-01-preview + - آخر بالاسم `AZURE_API_KEY` (باستخدام Key). + 6. انقر على `Add Connection` لحفظ اتصال LLM. + + + + 7. في `CrewAI AMP > Settings > Defaults > Crew Studio LLM Settings`، عيّن اتصال LLM والنموذج الجديدين كافتراضيين. + + + + 8. تأكد من إعدادات الوصول إلى الشبكة: + - في Azure، انتقل إلى `Azure OpenAI > اختر النشر`. + - انتقل إلى `Resource Management > Networking`. + - تأكد من تفعيل `Allow access from all networks`. إذا كان هذا الإعداد مقيداً، فقد يُحظر وصول CrewAI إلى نقطة نهاية Azure OpenAI. + + + + +## التحقق + +أنت جاهز! سيستخدم Crew Studio الآن اتصال Azure OpenAI الخاص بك. اختبر الاتصال بإنشاء طاقم أو مهمة بسيطة للتأكد من أن كل شيء يعمل بشكل صحيح. + +## استكشاف الأخطاء وإصلاحها + +إذا واجهت مشكلات: + +- تحقق من أن تنسيق Target URI يتطابق مع النمط المتوقع +- تحقق من صحة مفتاح API وأنه يملك الصلاحيات المناسبة +- تأكد من تهيئة الوصول إلى الشبكة للسماح باتصالات CrewAI +- تأكد من أن نموذج النشر يتطابق مع ما هيأته في CrewAI diff --git a/docs/ar/enterprise/guides/build-crew.mdx b/docs/ar/enterprise/guides/build-crew.mdx new file mode 100644 index 000000000..d6cd7f242 --- /dev/null +++ b/docs/ar/enterprise/guides/build-crew.mdx @@ -0,0 +1,48 @@ +--- +title: "بناء طاقم" +description: "الطاقم هو مجموعة من الوكلاء الذين يعملون معاً لإتمام مهمة." +icon: "people-arrows" +mode: "wide" +--- + +## نظرة عامة + +يبسّط [CrewAI AMP](https://app.crewai.com) عملية **إنشاء** و**نشر** و**إدارة** وكلاء الذكاء الاصطناعي في بيئات الإنتاج. + +## البدء + + + +### التثبيت والإعداد + + + اتبع دليل التثبيت القياسي لإعداد CrewAI CLI وإنشاء مشروعك + الأول. + + +### بناء طاقمك + + + اتبع دليل البدء السريع لإنشاء أول طاقم وكلاء باستخدام تهيئة + YAML. + + +## الدعم والموارد + +للدعم الخاص بالمؤسسات أو الأسئلة، تواصل مع فريق الدعم المخصص على [support@crewai.com](mailto:support@crewai.com). + + + احجز وقتاً مع فريقنا لمعرفة المزيد عن ميزات Enterprise وكيف يمكنها + إفادة مؤسستك. + diff --git a/docs/ar/enterprise/guides/capture_telemetry_logs.mdx b/docs/ar/enterprise/guides/capture_telemetry_logs.mdx new file mode 100644 index 000000000..1740c7c08 --- /dev/null +++ b/docs/ar/enterprise/guides/capture_telemetry_logs.mdx @@ -0,0 +1,39 @@ +--- +title: "تصدير OpenTelemetry" +description: "تصدير التتبعات والسجلات من عمليات نشر CrewAI AMP إلى مجمّع OpenTelemetry الخاص بك" +icon: "magnifying-glass-chart" +mode: "wide" +--- + +يمكن لـ CrewAI AMP تصدير **التتبعات** و**السجلات** من OpenTelemetry من عمليات النشر مباشرة إلى مجمّعك الخاص. يتيح لك ذلك مراقبة أداء الوكلاء وتتبع استدعاءات LLM وتصحيح الأخطاء باستخدام مجموعة المراقبة الحالية. + +تتبع بيانات القياس [اتفاقيات OpenTelemetry GenAI الدلالية](https://opentelemetry.io/docs/specs/semconv/gen-ai/) بالإضافة إلى سمات خاصة بـ CrewAI. + +## المتطلبات المسبقة + + + + يجب أن يكون لدى مؤسستك حساب CrewAI AMP نشط. + + + تحتاج إلى نقطة نهاية مجمّع متوافقة مع OpenTelemetry (مثل OTel Collector الخاص بك أو Datadog أو Grafana أو أي واجهة خلفية متوافقة مع OTLP). + + + +## إعداد مجمّع + +1. في CrewAI AMP، انتقل إلى **Settings** > **OpenTelemetry Collectors**. +2. انقر على **Add Collector**. +3. اختر نوع التكامل — **OpenTelemetry Traces** أو **OpenTelemetry Logs**. +4. هيّئ الاتصال: + - **Endpoint** — نقطة نهاية OTLP لمجمّعك (مثل `https://otel-collector.example.com:4317`). + - **Service Name** — اسم لتعريف هذه الخدمة في منصة المراقبة. + - **Custom Headers** *(اختياري)* — أضف رؤوس المصادقة أو التوجيه كأزواج مفتاح-قيمة. + - **Certificate** *(اختياري)* — قدم شهادة TLS إذا كان مجمّعك يتطلبها. +5. انقر على **Save**. + +![تهيئة مجمّع OpenTelemetry](/images/crewai-otel-collector-config.png) + + + يمكنك إضافة مجمّعات متعددة — على سبيل المثال، واحد للتتبعات وآخر للسجلات، أو الإرسال إلى واجهات خلفية مختلفة لأغراض مختلفة. + diff --git a/docs/ar/enterprise/guides/custom-mcp-server.mdx b/docs/ar/enterprise/guides/custom-mcp-server.mdx new file mode 100644 index 000000000..eb90dc518 --- /dev/null +++ b/docs/ar/enterprise/guides/custom-mcp-server.mdx @@ -0,0 +1,136 @@ +--- +title: "خوادم MCP المخصصة" +description: "اربط خوادم MCP الخاصة بك بـ CrewAI AMP مع وصول عام أو مصادقة بمفتاح API أو OAuth 2.0" +icon: "plug" +mode: "wide" +--- + +يدعم CrewAI AMP الاتصال بأي خادم MCP يُنفّذ [Model Context Protocol](https://modelcontextprotocol.io/). يمكنك إحضار خوادم عامة لا تتطلب مصادقة، وخوادم محمية بمفتاح API أو رمز حامل، وخوادم تستخدم OAuth 2.0 للوصول المفوّض الآمن. + +## المتطلبات المسبقة + + + + تحتاج إلى حساب [CrewAI AMP](https://app.crewai.com) نشط. + + + رابط خادم MCP الذي تريد الاتصال به. يجب أن يكون الخادم متاحاً من الإنترنت ويدعم نقل Streamable HTTP. + + + +## إضافة خادم MCP مخصص + + + + انتقل إلى **Tools & Integrations** في الشريط الجانبي الأيسر لـ CrewAI AMP، ثم اختر علامة تبويب **Connections**. + + + + انقر على زر **Add Custom MCP Server**. سيظهر مربع حوار مع نموذج التهيئة. + + + + - **Name** (مطلوب): اسم وصفي لخادم MCP (مثل "My Internal Tools Server"). + - **Description**: ملخص اختياري لما يقدمه خادم MCP هذا. + - **Server URL** (مطلوب): الرابط الكامل لنقطة نهاية خادم MCP (مثل `https://my-server.example.com/mcp`). + + + + اختر إحدى طرق المصادقة الثلاث المتاحة بناءً على كيفية تأمين خادم MCP. راجع الأقسام أدناه لتفاصيل كل طريقة. + + + + إذا كان خادم MCP يتطلب رؤوساً إضافية في كل طلب (مثل معرّفات المستأجر أو رؤوس التوجيه)، انقر على **+ Add Header** وقدم اسم الرأس وقيمته. يمكنك إضافة رؤوس مخصصة متعددة. + + + + انقر على **Create MCP Server** لحفظ الاتصال. سيظهر خادم MCP المخصص الآن في قائمة الاتصالات وستكون أدواته متاحة للاستخدام في طواقمك. + + + +## طرق المصادقة + +### بدون مصادقة + +اختر هذا الخيار عندما يكون خادم MCP متاحاً للجمهور ولا يتطلب أي بيانات اعتماد. هذا شائع للخوادم مفتوحة المصدر أو الخوادم الداخلية العاملة خلف VPN. + +### رمز المصادقة + +استخدم هذه الطريقة عندما يكون خادم MCP محمياً بمفتاح API أو رمز حامل. + + + خادم MCP مخصص برمز مصادقة + + +| الحقل | مطلوب | الوصف | +|-------|-------|-------| +| **Header Name** | نعم | اسم رأس HTTP الذي يحمل الرمز (مثل `X-API-Key`، `Authorization`). | +| **Value** | نعم | مفتاح API أو رمز الحامل الخاص بك. | +| **Add to** | لا | أين يتم إرفاق بيانات الاعتماد — **Header** (افتراضي) أو **Query parameter**. | + + +إذا كان خادمك يتوقع رمز `Bearer` في رأس `Authorization`، عيّن Header Name إلى `Authorization` والقيمة إلى `Bearer `. + + +### OAuth 2.0 + +استخدم هذه الطريقة لخوادم MCP التي تتطلب تفويض OAuth 2.0. سيتعامل CrewAI مع تدفق OAuth الكامل، بما في ذلك تحديث الرمز. + + + خادم MCP مخصص مع OAuth 2.0 + + +| الحقل | مطلوب | الوصف | +|-------|-------|-------| +| **Redirect URI** | — | مُعبأ مسبقاً وللقراءة فقط. انسخ هذا الرابط وسجّله كرابط إعادة توجيه مصرّح به في مزود OAuth. | +| **Authorization Endpoint** | نعم | الرابط الذي يُوجَّه إليه المستخدمون لتفويض الوصول (مثل `https://auth.example.com/oauth/authorize`). | +| **Token Endpoint** | نعم | الرابط المستخدم لتبادل رمز التفويض برمز وصول (مثل `https://auth.example.com/oauth/token`). | +| **Client ID** | نعم | معرّف عميل OAuth الصادر من مزودك. | +| **Client Secret** | لا | سر عميل OAuth. غير مطلوب للعملاء العامين باستخدام PKCE. | +| **Scopes** | لا | قائمة نطاقات مفصولة بمسافات للطلب (مثل `read write`). | +| **Token Auth Method** | لا | كيفية إرسال بيانات اعتماد العميل عند تبادل الرموز — **Standard (POST body)** أو **Basic Auth (header)**. الافتراضي هو Standard. | +| **PKCE Supported** | لا | فعّل إذا كان مزود OAuth يدعم Proof Key for Code Exchange. موصى به لتحسين الأمان. | + + +**اكتشاف تهيئة OAuth**: إذا كان مزود OAuth يدعم OpenID Connect Discovery، انقر على رابط **Discover OAuth Config** لملء نقاط نهاية التفويض والرمز تلقائياً من رابط `/.well-known/openid-configuration` الخاص بالمزود. + + +#### إعداد OAuth 2.0 خطوة بخطوة + + + + انسخ **Redirect URI** المعروض في النموذج وأضفه كرابط إعادة توجيه مصرّح به في إعدادات تطبيق مزود OAuth. + + + + املأ **Authorization Endpoint** و**Token Endpoint** و**Client ID**، واختيارياً **Client Secret** و**Scopes**. + + + + اختر **Token Auth Method** المناسبة. معظم المزودين يستخدمون الافتراضي **Standard (POST body)**. بعض المزودين القدامى يتطلبون **Basic Auth (header)**. + + + + حدد **PKCE Supported** إذا كان مزودك يدعمه. يضيف PKCE طبقة أمان إضافية لتدفق رمز التفويض وموصى به لجميع التكاملات الجديدة. + + + + انقر على **Create MCP Server**. سيتم توجيهك إلى مزود OAuth لتفويض الوصول. بمجرد التفويض، سيخزن CrewAI الرموز ويحدّثها تلقائياً حسب الحاجة. + + + +## استخدام خادم MCP المخصص + +بمجرد الاتصال، تظهر أدوات خادم MCP المخصص جنباً إلى جنب مع الاتصالات المدمجة في صفحة **Tools & Integrations**. يمكنك: + +- **تعيين الأدوات للوكلاء** في طواقمك تماماً كأي أداة CrewAI أخرى. +- **إدارة الرؤية** للتحكم في أعضاء الفريق الذين يمكنهم استخدام الخادم. +- **تعديل أو إزالة** الاتصال في أي وقت من قائمة الاتصالات. + + +إذا أصبح خادم MCP غير قابل للوصول أو انتهت صلاحية بيانات الاعتماد، ستفشل استدعاءات الأدوات التي تستخدم ذلك الخادم. تأكد من استقرار رابط الخادم وتحديث بيانات الاعتماد. + + + + تواصل مع فريق الدعم للمساعدة في تهيئة خادم MCP المخصص أو استكشاف الأخطاء. + diff --git a/docs/ar/enterprise/guides/deploy-to-amp.mdx b/docs/ar/enterprise/guides/deploy-to-amp.mdx new file mode 100644 index 000000000..befc894d7 --- /dev/null +++ b/docs/ar/enterprise/guides/deploy-to-amp.mdx @@ -0,0 +1,445 @@ +--- +title: "النشر على AMP" +description: "انشر طاقمك أو تدفقك على CrewAI AMP" +icon: "rocket" +mode: "wide" +--- + + + بعد إنشاء طاقم أو تدفق محلياً (أو عبر Crew Studio)، الخطوة التالية هي + نشره على منصة CrewAI AMP. يغطي هذا الدليل طرق نشر متعددة + لمساعدتك في اختيار النهج الأفضل لسير عملك. + + +## المتطلبات المسبقة + + + + يجب أن يكون لديك طاقم أو تدفق يعمل بنجاح محلياً. + اتبع [دليل التحضير](/ar/enterprise/guides/prepare-for-deployment) للتحقق من بنية مشروعك. + + + يجب أن يكون الكود في مستودع GitHub (لطريقة تكامل + GitHub) + + + + + **الطواقم مقابل التدفقات**: يمكن نشر كلا نوعي المشاريع كـ "أتمتات" على CrewAI AMP. + عملية النشر هي نفسها، لكن لهما بنى مشاريع مختلفة. + راجع [التحضير للنشر](/ar/enterprise/guides/prepare-for-deployment) للتفاصيل. + + +## الخيار 1: النشر باستخدام CrewAI CLI + +يوفر CLI أسرع طريقة لنشر الطواقم أو التدفقات المطورة محلياً على منصة AMP. +يكتشف CLI تلقائياً نوع مشروعك من `pyproject.toml` ويبني وفقاً لذلك. + + + + إذا لم تكن قد فعلت بالفعل، ثبّت CrewAI CLI: + + ```bash + pip install crewai[tools] + ``` + + + يأتي CLI مع حزمة CrewAI الرئيسية، لكن الإضافة `[tools]` تضمن حصولك على جميع اعتماديات النشر. + + + + + + أولاً، تحتاج لمصادقة CLI مع منصة CrewAI AMP: + + ```bash + # إذا كان لديك حساب CrewAI AMP بالفعل، أو تريد إنشاء واحد: + crewai login + ``` + + عند تشغيل أي من الأمرين، سيقوم CLI بـ: + 1. عرض رابط ورمز جهاز فريد + 2. فتح متصفحك على صفحة المصادقة + 3. طلب تأكيد الجهاز + 4. إتمام عملية المصادقة + + عند المصادقة الناجحة، سترى رسالة تأكيد في الطرفية! + + + + + + من مجلد مشروعك، شغّل: + + ```bash + crewai deploy create + ``` + + سيقوم هذا الأمر بـ: + 1. اكتشاف معلومات مستودع GitHub + 2. تحديد متغيرات البيئة في ملف `.env` المحلي + 3. نقل هذه المتغيرات بأمان إلى منصة Enterprise + 4. إنشاء عملية نشر جديدة بمعرّف فريد + + عند الإنشاء الناجح، سترى رسالة مثل: + ```shell + Deployment created successfully! + Name: your_project_name + Deployment ID: 01234567-89ab-cdef-0123-456789abcdef + Current Status: Deploy Enqueued + ``` + + + + + + تتبع حالة النشر بـ: + + ```bash + crewai deploy status + ``` + + للسجلات المفصلة لعملية البناء: + + ```bash + crewai deploy logs + ``` + + + يستغرق النشر الأول عادة حوالي دقيقة واحدة. + + + + + +## أوامر CLI إضافية + +يقدم CrewAI CLI عدة أوامر لإدارة عمليات النشر: + +```bash +# عرض جميع عمليات النشر +crewai deploy list + +# الحصول على حالة النشر +crewai deploy status + +# عرض سجلات النشر +crewai deploy logs + +# دفع التحديثات بعد تغييرات الكود +crewai deploy push + +# إزالة عملية نشر +crewai deploy remove +``` + +## الخيار 2: النشر مباشرة عبر واجهة الويب + +يمكنك أيضاً نشر طواقمك أو تدفقاتك مباشرة عبر واجهة ويب CrewAI AMP بربط حساب GitHub. لا يتطلب هذا النهج استخدام CLI على جهازك المحلي. تكتشف المنصة تلقائياً نوع مشروعك وتتعامل مع البناء بشكل مناسب. + + + + + +تحتاج لدفع طاقمك إلى مستودع GitHub. إذا لم تكن قد أنشأت طاقماً بعد، يمكنك [اتباع هذا الدليل](/ar/quickstart). + + + + + + 1. سجّل الدخول إلى [CrewAI AMP](https://app.crewai.com) + 2. انقر على زر "Connect GitHub" + + + ![زر ربط GitHub](/images/enterprise/connect-github.png) + + + + + + + بعد ربط حساب GitHub، ستتمكن من اختيار المستودع للنشر: + + + ![اختيار المستودع](/images/enterprise/select-repo.png) + + + + + + + قبل النشر، ستحتاج لإعداد متغيرات البيئة للاتصال بمزود LLM أو خدمات أخرى: + + 1. يمكنك إضافة المتغيرات فردياً أو بشكل جماعي + 2. أدخل متغيرات البيئة بتنسيق `KEY=VALUE` (واحد لكل سطر) + + + ![تعيين متغيرات البيئة](/images/enterprise/set-env-variables.png) + + + + تستخدم حزم Python خاصة؟ ستحتاج لإضافة بيانات اعتماد السجل هنا أيضاً. + راجع [سجلات الحزم الخاصة](/ar/enterprise/guides/private-package-registry) للمتغيرات المطلوبة. + + + + + + + 1. انقر على زر "Deploy" لبدء عملية النشر + 2. يمكنك مراقبة التقدم عبر شريط التقدم + 3. يستغرق النشر الأول عادة حوالي دقيقة واحدة + + + ![تقدم النشر](/images/enterprise/deploy-progress.png) + + + بمجرد اكتمال النشر، سترى: + - رابط طاقمك الفريد + - رمز Bearer لحماية API طاقمك + - زر "Delete" إذا كنت تحتاج لإزالة النشر + + + + + +## الخيار 3: إعادة النشر باستخدام API (تكامل CI/CD) + +لعمليات النشر الآلية في خطوط أنابيب CI/CD، يمكنك استخدام CrewAI API لتشغيل إعادة نشر الطواقم الحالية. هذا مفيد بشكل خاص لـ GitHub Actions وJenkins أو سير عمل الأتمتة الأخرى. + + + + + انتقل إلى إعدادات حساب CrewAI AMP لإنشاء رمز API: + + 1. انتقل إلى [app.crewai.com](https://app.crewai.com) + 2. انقر على **Settings** → **Account** → **Personal Access Token** + 3. أنشئ رمزاً جديداً وانسخه بأمان + 4. خزّن هذا الرمز كسر في نظام CI/CD + + + + + + حدد موقع المعرّف الفريد لطاقمك المنشور: + + 1. انتقل إلى **Automations** في لوحة تحكم CrewAI AMP + 2. اختر الأتمتة/الطاقم الحالي + 3. انقر على **Additional Details** + 4. انسخ **UUID** — يحدد هذا نشر طاقمك المحدد + + + + + + استخدم نقطة نهاية Deploy API لتشغيل إعادة النشر: + + ```bash + curl -i -X POST \ + -H "Authorization: Bearer YOUR_PERSONAL_ACCESS_TOKEN" \ + https://app.crewai.com/crewai_plus/api/v1/crews/YOUR-AUTOMATION-UUID/deploy + + # HTTP/2 200 + # content-type: application/json + # + # { + # "uuid": "your-automation-uuid", + # "status": "Deploy Enqueued", + # "public_url": "https://your-crew-deployment.crewai.com", + # "token": "your-bearer-token" + # } + ``` + + + إذا تم إنشاء أتمتتك متصلة بـ Git أولاً، سيسحب API تلقائياً أحدث التغييرات من مستودعك قبل إعادة النشر. + + + + + + + إليك سير عمل GitHub Actions مع مشغلات نشر أكثر تعقيداً: + + ```yaml + name: Deploy CrewAI Automation + + on: + push: + branches: [ main ] + pull_request: + types: [ labeled ] + release: + types: [ published ] + + jobs: + deploy: + runs-on: ubuntu-latest + if: | + (github.event_name == 'push' && github.ref == 'refs/heads/main') || + (github.event_name == 'pull_request' && contains(github.event.pull_request.labels.*.name, 'deploy')) || + (github.event_name == 'release') + steps: + - name: Trigger CrewAI Redeployment + run: | + curl -X POST \ + -H "Authorization: Bearer ${{ secrets.CREWAI_PAT }}" \ + https://app.crewai.com/crewai_plus/api/v1/crews/${{ secrets.CREWAI_AUTOMATION_UUID }}/deploy + ``` + + + أضف `CREWAI_PAT` و`CREWAI_AUTOMATION_UUID` كأسرار مستودع. لعمليات نشر PR، أضف تسمية "deploy" لتشغيل سير العمل. + + + + + + +## التفاعل مع أتمتتك المنشورة + +بمجرد اكتمال النشر، يمكنك الوصول إلى طاقمك عبر: + +1. **REST API**: تنشئ المنصة نقطة نهاية HTTPS فريدة بهذه المسارات الرئيسية: + + - `/inputs`: يعرض معاملات الإدخال المطلوبة + - `/kickoff`: يبدأ التنفيذ بالمدخلات المقدمة + - `/status/{kickoff_id}`: يتحقق من حالة التنفيذ + +2. **واجهة الويب**: زر [app.crewai.com](https://app.crewai.com) للوصول إلى: + - **علامة تبويب Status**: عرض معلومات النشر وتفاصيل نقطة نهاية API ورمز المصادقة + - **علامة تبويب Run**: تمثيل مرئي لبنية طاقمك + - **علامة تبويب Executions**: سجل جميع عمليات التنفيذ + - **علامة تبويب Metrics**: تحليلات الأداء + - **علامة تبويب Traces**: رؤى التنفيذ المفصلة + +### تشغيل عملية تنفيذ + +من لوحة تحكم Enterprise، يمكنك: + +1. النقر على اسم طاقمك لفتح تفاصيله +2. اختيار "Trigger Crew" من واجهة الإدارة +3. إدخال المدخلات المطلوبة في النافذة المنبثقة +4. مراقبة التقدم أثناء مرور التنفيذ عبر خط الأنابيب + +### المراقبة والتحليلات + +توفر منصة Enterprise ميزات مراقبة شاملة: + +- **إدارة التنفيذ**: تتبع عمليات التشغيل النشطة والمكتملة +- **التتبعات**: تحليلات مفصلة لكل عملية تنفيذ +- **المقاييس**: استخدام الرموز وأوقات التنفيذ والتكاليف +- **عرض الجدول الزمني**: تمثيل مرئي لتسلسل المهام + +### ميزات متقدمة + +تقدم منصة Enterprise أيضاً: + +- **إدارة متغيرات البيئة**: تخزين وإدارة مفاتيح API بأمان +- **اتصالات LLM**: تهيئة التكاملات مع مزودي LLM المختلفين +- **مستودع الأدوات المخصصة**: إنشاء ومشاركة وتثبيت الأدوات +- **Crew Studio**: بناء الطواقم عبر واجهة محادثة دون كتابة كود + +## استكشاف أخطاء النشر وإصلاحها + +إذا فشل النشر، تحقق من هذه المشكلات الشائعة: + +### فشل البناء + +#### ملف uv.lock مفقود + +**العرض**: فشل البناء مبكراً مع أخطاء حل الاعتماديات + +**الحل**: أنشئ ملف القفل وارفعه: + +```bash +uv lock +git add uv.lock +git commit -m "Add uv.lock for deployment" +git push +``` + + + ملف `uv.lock` مطلوب لجميع عمليات النشر. بدونه، لا يمكن للمنصة + تثبيت اعتمادياتك بشكل موثوق. + + +#### بنية المشروع الخاطئة + +**العرض**: أخطاء "Could not find entry point" أو "Module not found" + +**الحل**: تحقق من أن مشروعك يتطابق مع البنية المتوقعة: + +- **كل من الطواقم والتدفقات**: يجب أن تكون نقطة الدخول في `src/project_name/main.py` +- **الطواقم**: تستخدم دالة `run()` كنقطة دخول +- **التدفقات**: تستخدم دالة `kickoff()` كنقطة دخول + +راجع [التحضير للنشر](/ar/enterprise/guides/prepare-for-deployment) لمخططات البنية المفصلة. + +#### مُزخرف CrewBase مفقود + +**العرض**: أخطاء "Crew not found" أو "Config not found" أو أخطاء تهيئة الوكيل/المهمة + +**الحل**: تأكد من أن **جميع** فئات الطاقم تستخدم مُزخرف `@CrewBase`: + +```python +from crewai.project import CrewBase, agent, crew, task + +@CrewBase # This decorator is REQUIRED +class YourCrew(): + """Your crew description""" + + @agent + def my_agent(self) -> Agent: + return Agent( + config=self.agents_config['my_agent'], # type: ignore[index] + verbose=True + ) + + # ... rest of crew definition +``` + + + ينطبق هذا على الطواقم المستقلة والطواقم المضمنة داخل مشاريع التدفق. + كل فئة طاقم تحتاج المُزخرف. + + +#### نوع pyproject.toml غير صحيح + +**العرض**: نجاح البناء لكن فشل وقت التشغيل، أو سلوك غير متوقع + +**الحل**: تحقق من أن قسم `[tool.crewai]` يتطابق مع نوع مشروعك: + +```toml +# For Crew projects: +[tool.crewai] +type = "crew" + +# For Flow projects: +[tool.crewai] +type = "flow" +``` + +### فشل وقت التشغيل + +#### فشل اتصال LLM + +**العرض**: أخطاء مفتاح API، "model not found"، أو فشل المصادقة + +**الحل**: +1. تحقق من صحة تعيين مفتاح API لمزود LLM في متغيرات البيئة +2. تأكد من تطابق أسماء متغيرات البيئة مع ما يتوقعه الكود +3. اختبر محلياً بنفس متغيرات البيئة بالضبط قبل النشر + +#### أخطاء تنفيذ الطاقم + +**العرض**: يبدأ الطاقم لكن يفشل أثناء التنفيذ + +**الحل**: +1. تحقق من سجلات التنفيذ في لوحة تحكم AMP (علامة تبويب Traces) +2. تحقق من أن جميع الأدوات لديها مفاتيح API المطلوبة مُهيأة +3. تأكد من صحة تهيئات الوكلاء في `agents.yaml` +4. تحقق من تهيئات المهام في `tasks.yaml` بحثاً عن أخطاء الصياغة + + + تواصل مع فريق الدعم للمساعدة في مشاكل النشر أو أسئلة حول + منصة AMP. + diff --git a/docs/ar/enterprise/guides/enable-crew-studio.mdx b/docs/ar/enterprise/guides/enable-crew-studio.mdx new file mode 100644 index 000000000..7f1b03a02 --- /dev/null +++ b/docs/ar/enterprise/guides/enable-crew-studio.mdx @@ -0,0 +1,182 @@ +--- +title: "تفعيل Crew Studio" +description: "تفعيل Crew Studio على CrewAI AMP" +icon: "comments" +mode: "wide" +--- + + + Crew Studio هو أداة قوية **بدون كود/منخفضة الكود** تتيح لك بسرعة + بناء أو هيكلة الطواقم عبر واجهة محادثة. + + +## ما هو Crew Studio؟ + +Crew Studio هو طريقة مبتكرة لإنشاء طواقم وكلاء الذكاء الاصطناعي بدون كتابة كود. + + + ![واجهة Crew Studio](/images/enterprise/crew-studio-interface.png) + + +مع Crew Studio، يمكنك: + +- الدردشة مع مساعد الطاقم لوصف مشكلتك +- إنشاء الوكلاء والمهام تلقائياً +- اختيار الأدوات المناسبة +- تهيئة المدخلات الضرورية +- إنشاء كود قابل للتنزيل للتخصيص +- النشر مباشرة على منصة CrewAI AMP + +## خطوات التهيئة + +قبل البدء باستخدام Crew Studio، تحتاج لتهيئة اتصالات LLM: + + + + انتقل إلى علامة تبويب **LLM Connections** في لوحة تحكم CrewAI AMP وأنشئ اتصال LLM جديداً. + + + يمكنك استخدام أي مزود LLM تريده ويدعمه CrewAI. + + + هيّئ اتصال LLM: + + - أدخل `Connection Name` (مثل `OpenAI`) + - اختر مزود النموذج: `openai` أو `azure` + - اختر النماذج التي تريد استخدامها في طواقم Studio + - نوصي بـ `gpt-4o` و`o1-mini` و`gpt-4o-mini` على الأقل + - أضف مفتاح API كمتغير بيئة: + - لـ OpenAI: أضف `OPENAI_API_KEY` مع مفتاح API + - لـ Azure OpenAI: راجع [هذه المقالة](https://blog.crewai.com/configuring-azure-openai-with-crewai-a-comprehensive-guide/) لتفاصيل التهيئة + - انقر على `Add Connection` لحفظ التهيئة + + + ![تهيئة اتصال LLM](/images/enterprise/llm-connection-config.png) + + + + + + بمجرد إتمام الإعداد، سترى الاتصال الجديد مُضافاً إلى قائمة الاتصالات المتاحة. + + + ![تم إضافة الاتصال](/images/enterprise/connection-added.png) + + + + + + في القائمة الرئيسية، انتقل إلى **Settings → Defaults** وهيّئ إعدادات LLM الافتراضية: + + - اختر النماذج الافتراضية للوكلاء والمكونات الأخرى + - عيّن التهيئات الافتراضية لـ Crew Studio + + انقر على `Save Settings` لتطبيق تغييراتك. + + + ![تهيئة إعدادات LLM الافتراضية](/images/enterprise/llm-defaults.png) + + + + + +## استخدام Crew Studio + +الآن بعد تهيئة اتصال LLM والإعدادات الافتراضية، أنت جاهز لبدء استخدام Crew Studio! + + + + انتقل إلى قسم **Studio** في لوحة تحكم CrewAI AMP. + + + + ابدأ محادثة مع مساعد الطاقم بوصف المشكلة التي تريد حلها: + + ```md + I need a crew that can research the latest AI developments and create a summary report. + ``` + + سيطرح مساعد الطاقم أسئلة توضيحية لفهم متطلباتك بشكل أفضل. + + + + + راجع تهيئة الطاقم المُنشأ، بما في ذلك: + + - الوكلاء وأدوارهم + - المهام المطلوب تنفيذها + - المدخلات المطلوبة + - الأدوات المستخدمة + + هذه فرصتك لتنقيح التهيئة قبل المتابعة. + + + + + بمجرد رضاك عن التهيئة، يمكنك: + + - تنزيل الكود المُنشأ للتخصيص المحلي + - نشر الطاقم مباشرة على منصة CrewAI AMP + - تعديل التهيئة وإعادة إنشاء الطاقم + + + + + بعد النشر، اختبر طاقمك بمدخلات نموذجية للتأكد من أنه يعمل كما هو متوقع. + + + + + للحصول على أفضل النتائج، قدم أوصافاً واضحة ومفصلة لما تريد أن + يحققه طاقمك. ضمّن مدخلات ومخرجات محددة متوقعة في + وصفك. + + +## مثال على سير العمل + +إليك سير عمل نموذجي لإنشاء طاقم مع Crew Studio: + + + + ابدأ بوصف مشكلتك: + + ```md + I need a crew that can analyze financial news and provide investment recommendations + ``` + + + +{" "} + + أجب على أسئلة التوضيح من مساعد الطاقم لتنقيح + متطلباتك. + + + + راجع خطة الطاقم المُنشأة، التي قد تتضمن: + + - وكيل بحث لجمع الأخبار المالية + - وكيل تحليل لتفسير البيانات + - وكيل توصيات لتقديم نصائح استثمارية + + + +{" "} + + وافق على الخطة أو اطلب تغييرات إذا لزم الأمر. + + +{" "} + + نزّل الكود للتخصيص أو انشر مباشرة على المنصة. + + + + اختبر طاقمك بمدخلات نموذجية ونقّح حسب الحاجة. + + + + + تواصل مع فريق الدعم للمساعدة في Crew Studio أو أي ميزات أخرى في CrewAI + AMP. + diff --git a/docs/ar/enterprise/guides/gmail-trigger.mdx b/docs/ar/enterprise/guides/gmail-trigger.mdx new file mode 100644 index 000000000..5423109c0 --- /dev/null +++ b/docs/ar/enterprise/guides/gmail-trigger.mdx @@ -0,0 +1,97 @@ +--- +title: "مشغل Gmail" +description: "تشغيل الأتمتات عند حدوث أحداث Gmail (مثل رسائل بريد إلكتروني جديدة، تسميات)." +icon: "envelope" +mode: "wide" +--- + +## نظرة عامة + +استخدم مشغل Gmail لتشغيل طواقمك المنشورة عند حدوث أحداث Gmail في الحسابات المتصلة، مثل استلام رسالة بريد إلكتروني جديدة أو رسائل تطابق تسمية/فلتر. + + + تأكد من ربط Gmail في Tools & Integrations وتفعيل المشغل + لعملية النشر. + + +## تفعيل مشغل Gmail + +1. افتح عملية النشر في CrewAI AMP +2. انتقل إلى علامة تبويب **Triggers** +3. حدد موقع **Gmail** وبدّل مفتاح التبديل للتفعيل + + + تفعيل أو تعطيل المشغلات بالتبديل + + +## مثال: معالجة الرسائل الجديدة + +عند وصول رسالة بريد إلكتروني جديدة، سيرسل مشغل Gmail الحمولة إلى طاقمك أو تدفقك. فيما يلي مثال على طاقم يحلل ويعالج حمولة المشغل. + +```python +@CrewBase +class GmailProcessingCrew: + @agent + def parser(self) -> Agent: + return Agent( + config=self.agents_config['parser'], + ) + + @task + def parse_gmail_payload(self) -> Task: + return Task( + config=self.tasks_config['parse_gmail_payload'], + agent=self.parser(), + ) + + @task + def act_on_email(self) -> Task: + return Task( + config=self.tasks_config['act_on_email'], + agent=self.parser(), + ) +``` + +ستكون حمولة Gmail متاحة عبر آليات السياق القياسية. + +### الاختبار المحلي + +اختبر تكامل مشغل Gmail محلياً باستخدام CrewAI CLI: + +```bash +# عرض جميع المشغلات المتاحة +crewai triggers list + +# محاكاة مشغل Gmail بحمولة واقعية +crewai triggers run gmail/new_email_received +``` + +سينفذ أمر `crewai triggers run` طاقمك بحمولة Gmail كاملة، مما يتيح لك اختبار منطق التحليل قبل النشر. + + + استخدم `crewai triggers run gmail/new_email_received` (وليس `crewai run`) لمحاكاة + تنفيذ المشغل أثناء التطوير. بعد النشر، سيتلقى طاقمك + حمولة المشغل تلقائياً. + + +## مراقبة عمليات التنفيذ + +تتبع سجل وأداء عمليات التشغيل المُشغّلة: + + + قائمة عمليات التنفيذ المُشغّلة بواسطة الأتمتة + + +## استكشاف الأخطاء وإصلاحها + +- تأكد من ربط Gmail في Tools & Integrations +- تحقق من تفعيل مشغل Gmail في علامة تبويب Triggers +- اختبر محلياً بـ `crewai triggers run gmail/new_email_received` لرؤية هيكل الحمولة بالضبط +- تحقق من سجلات التنفيذ وتأكد من تمرير الحمولة كـ `crewai_trigger_payload` +- تذكر: استخدم `crewai triggers run` (وليس `crewai run`) لمحاكاة تنفيذ المشغل diff --git a/docs/ar/enterprise/guides/google-calendar-trigger.mdx b/docs/ar/enterprise/guides/google-calendar-trigger.mdx new file mode 100644 index 000000000..542df5b18 --- /dev/null +++ b/docs/ar/enterprise/guides/google-calendar-trigger.mdx @@ -0,0 +1,83 @@ +--- +title: "مشغل Google Calendar" +description: "تشغيل الطواقم عند إنشاء أو تحديث أو إلغاء أحداث Google Calendar" +icon: "calendar" +mode: "wide" +--- + +## نظرة عامة + +استخدم مشغل Google Calendar لإطلاق الأتمتات كلما تغيرت أحداث التقويم. تشمل حالات الاستخدام الشائعة إحاطة الفريق قبل اجتماع، وإخطار أصحاب المصلحة عند إلغاء حدث هام، أو تلخيص الجداول اليومية. + + + تأكد من ربط Google Calendar في **Tools & Integrations** وتفعيله + لعملية النشر التي تريد أتمتتها. + + +## تفعيل مشغل Google Calendar + +1. افتح عملية النشر في CrewAI AMP +2. انتقل إلى علامة تبويب **Triggers** +3. حدد موقع **Google Calendar** وبدّل مفتاح التبديل للتفعيل + + + تفعيل أو تعطيل المشغلات بالتبديل + + +## مثال: تلخيص تفاصيل الاجتماع + +المقتطف أدناه يعكس مثال `calendar-event-crew.py` في مستودع المشغلات. يحلل الحمولة، ويحلل الحاضرين والتوقيت، وينتج ملخصاً للاجتماع للأدوات اللاحقة. + +```python +from calendar_event_crew import GoogleCalendarEventTrigger + +crew = GoogleCalendarEventTrigger().crew() +result = crew.kickoff({ + "crewai_trigger_payload": calendar_payload, +}) +print(result.raw) +``` + +استخدم `crewai_trigger_payload` تماماً كما يتم تسليمه من المشغل حتى يتمكن الطاقم من استخراج الحقول المناسبة. + +## الاختبار المحلي + +اختبر تكامل مشغل Google Calendar محلياً باستخدام CrewAI CLI: + +```bash +# عرض جميع المشغلات المتاحة +crewai triggers list + +# محاكاة مشغل Google Calendar بحمولة واقعية +crewai triggers run google_calendar/event_changed +``` + +سينفذ أمر `crewai triggers run` طاقمك بحمولة Calendar كاملة، مما يتيح لك اختبار منطق التحليل قبل النشر. + + + استخدم `crewai triggers run google_calendar/event_changed` (وليس `crewai run`) لمحاكاة + تنفيذ المشغل أثناء التطوير. بعد النشر، سيتلقى طاقمك + حمولة المشغل تلقائياً. + + +## مراقبة عمليات التنفيذ + +تتبع قائمة **Executions** في لوحة تحكم النشر كل عملية تشغيل مُشغّلة وتعرض بيانات الحمولة الوصفية وملخصات المخرجات والأخطاء. + + + قائمة عمليات التنفيذ المُشغّلة بواسطة الأتمتة + + +## استكشاف الأخطاء وإصلاحها + +- تأكد من ربط حساب Google الصحيح وتفعيل المشغل +- اختبر محلياً بـ `crewai triggers run google_calendar/event_changed` لرؤية هيكل الحمولة بالضبط +- تأكد من أن سير عملك يتعامل مع أحداث اليوم الكامل (الحمولات تستخدم `start.date` و`end.date` بدلاً من الطوابع الزمنية) +- تحقق من سجلات التنفيذ إذا كانت التذكيرات أو مصفوفات الحاضرين مفقودة — قد تحد صلاحيات التقويم من الحقول في الحمولة +- تذكر: استخدم `crewai triggers run` (وليس `crewai run`) لمحاكاة تنفيذ المشغل diff --git a/docs/ar/enterprise/guides/google-drive-trigger.mdx b/docs/ar/enterprise/guides/google-drive-trigger.mdx new file mode 100644 index 000000000..0f4c05ec4 --- /dev/null +++ b/docs/ar/enterprise/guides/google-drive-trigger.mdx @@ -0,0 +1,80 @@ +--- +title: "مشغل Google Drive" +description: "الاستجابة لأحداث ملفات Google Drive بطواقم آلية" +icon: "folder" +mode: "wide" +--- + +## نظرة عامة + +شغّل أتمتاتك عند إنشاء أو تحديث أو حذف ملفات في Google Drive. تشمل سير العمل النموذجية تلخيص المحتوى المُحمّل حديثاً، وتطبيق سياسات المشاركة، أو إخطار المالكين عند تغيير ملفات هامة. + + + اربط Google Drive في **Tools & Integrations** وتأكد من تفعيل المشغل + للأتمتة التي تريد مراقبتها. + + +## تفعيل مشغل Google Drive + +1. افتح عملية النشر في CrewAI AMP +2. انتقل إلى علامة تبويب **Triggers** +3. حدد موقع **Google Drive** وبدّل مفتاح التبديل للتفعيل + + + تفعيل أو تعطيل المشغلات بالتبديل + + +## مثال: تلخيص نشاط الملفات + +تحلل طواقم Drive النموذجية الحمولة لاستخراج بيانات الملف الوصفية وتقييم الصلاحيات ونشر ملخص. + +```python +from drive_file_crew import GoogleDriveFileTrigger + +crew = GoogleDriveFileTrigger().crew() +crew.kickoff({ + "crewai_trigger_payload": drive_payload, +}) +``` + +## الاختبار المحلي + +اختبر تكامل مشغل Google Drive محلياً باستخدام CrewAI CLI: + +```bash +# عرض جميع المشغلات المتاحة +crewai triggers list + +# محاكاة مشغل Google Drive بحمولة واقعية +crewai triggers run google_drive/file_changed +``` + +سينفذ أمر `crewai triggers run` طاقمك بحمولة Drive كاملة، مما يتيح لك اختبار منطق التحليل قبل النشر. + + + استخدم `crewai triggers run google_drive/file_changed` (وليس `crewai run`) لمحاكاة + تنفيذ المشغل أثناء التطوير. بعد النشر، سيتلقى طاقمك + حمولة المشغل تلقائياً. + + +## مراقبة عمليات التنفيذ + +تتبع سجل وأداء عمليات التشغيل المُشغّلة عبر قائمة **Executions** في لوحة تحكم النشر. + + + قائمة عمليات التنفيذ المُشغّلة بواسطة الأتمتة + + +## استكشاف الأخطاء وإصلاحها + +- تحقق من ربط Google Drive وتفعيل مفتاح التبديل للمشغل +- اختبر محلياً بـ `crewai triggers run google_drive/file_changed` لرؤية هيكل الحمولة بالضبط +- إذا كانت الحمولة تفتقد بيانات الصلاحيات، تأكد من أن الحساب المتصل لديه صلاحية الوصول إلى الملف أو المجلد +- يرسل المشغل معرّفات الملفات فقط؛ استخدم Drive API إذا كنت تحتاج جلب المحتوى الثنائي أثناء تشغيل الطاقم +- تذكر: استخدم `crewai triggers run` (وليس `crewai run`) لمحاكاة تنفيذ المشغل diff --git a/docs/ar/enterprise/guides/hubspot-trigger.mdx b/docs/ar/enterprise/guides/hubspot-trigger.mdx new file mode 100644 index 000000000..20c31aef6 --- /dev/null +++ b/docs/ar/enterprise/guides/hubspot-trigger.mdx @@ -0,0 +1,61 @@ +--- +title: "مشغل HubSpot" +description: "تشغيل طواقم CrewAI مباشرة من سير عمل HubSpot" +icon: "hubspot" +mode: "wide" +--- + +يقدم هذا الدليل عملية خطوة بخطوة لإعداد مشغلات HubSpot لـ CrewAI AMP، مما يتيح لك بدء الطواقم مباشرة من سير عمل HubSpot. + +## المتطلبات المسبقة + +- حساب CrewAI AMP +- حساب HubSpot مع ميزة [HubSpot Workflows](https://knowledge.hubspot.com/workflows/create-workflows) + +## خطوات الإعداد + + + + - سجّل الدخول إلى `حساب CrewAI AMP > Triggers` - اختر `HubSpot` من + قائمة المشغلات المتاحة - اختر حساب HubSpot الذي تريد ربطه + بـ CrewAI AMP - اتبع التعليمات على الشاشة لتفويض وصول CrewAI AMP + إلى حساب HubSpot - ستظهر رسالة تأكيد بمجرد + ربط HubSpot بنجاح مع CrewAI AMP + + + - سجّل الدخول إلى `حساب HubSpot > Automations > Workflows > New workflow` + - اختر نوع سير العمل المناسب لاحتياجاتك (مثل Start from scratch) - + في منشئ سير العمل، انقر على أيقونة Plus (+) لإضافة إجراء جديد. - + اختر `Integrated apps > CrewAI > Kickoff a Crew`. - اختر الطاقم الذي + تريد تشغيله. - انقر على `Save` لإضافة الإجراء إلى سير عملك + + سير عمل HubSpot 1 + + + + - بعد خطوة Kickoff a Crew، انقر على أيقونة Plus (+) لإضافة + إجراء جديد. - على سبيل المثال، لإرسال إشعار بريد إلكتروني داخلي، اختر + `Communications > Send internal email notification` - في حقل Body، + انقر على `Insert data`، اختر `View properties or action outputs from > Action + outputs > Crew Result` لتضمين بيانات الطاقم في البريد الإلكتروني + + سير عمل HubSpot 2 + + - هيّئ أي إجراءات إضافية حسب الحاجة - راجع خطوات + سير عملك للتأكد من إعداد كل شيء بشكل صحيح - فعّل سير العمل + + سير عمل HubSpot 3 + + + + +لمزيد من المعلومات المفصلة حول الإجراءات المتاحة وخيارات التخصيص، راجع [وثائق HubSpot Workflows](https://knowledge.hubspot.com/workflows/create-workflows). diff --git a/docs/ar/enterprise/guides/human-in-the-loop.mdx b/docs/ar/enterprise/guides/human-in-the-loop.mdx new file mode 100644 index 000000000..468f69e2e --- /dev/null +++ b/docs/ar/enterprise/guides/human-in-the-loop.mdx @@ -0,0 +1,157 @@ +--- +title: "سير عمل HITL" +description: "تعلم كيفية تنفيذ سير عمل Human-In-The-Loop في CrewAI لتعزيز اتخاذ القرار" +icon: "user-check" +mode: "wide" +--- + +Human-In-The-Loop (HITL) هو نهج قوي يجمع بين الذكاء الاصطناعي والخبرة البشرية لتعزيز اتخاذ القرار وتحسين نتائج المهام. يوضح هذا الدليل كيفية تنفيذ HITL داخل CrewAI Enterprise. + +## نهجا HITL في CrewAI + +يقدم CrewAI نهجين لتنفيذ سير عمل Human-In-The-Loop: + +| النهج | الأفضل لـ | الإصدار | +|-------|-----------|---------| +| **قائم على التدفق** (مُزخرف `@human_feedback`) | الإنتاج مع واجهة Enterprise، سير عمل البريد الإلكتروني أولاً، ميزات المنصة الكاملة | **1.8.0+** | +| **قائم على Webhook** | التكاملات المخصصة، الأنظمة الخارجية (Slack، Teams، إلخ.)، الإعدادات القديمة | جميع الإصدارات | + +## HITL القائم على التدفق مع منصة Enterprise + + +يتطلب مُزخرف `@human_feedback` **إصدار CrewAI 1.8.0 أو أعلى**. + + +عند استخدام مُزخرف `@human_feedback` في تدفقاتك، يوفر CrewAI Enterprise **نظام HITL يعتمد على البريد الإلكتروني أولاً** يمكّن أي شخص لديه عنوان بريد إلكتروني من الاستجابة لطلبات المراجعة: + + + + يتلقى المستجيبون إشعارات بريد إلكتروني ويمكنهم الرد مباشرة — لا حاجة لتسجيل الدخول. + + + راجع واستجب لطلبات HITL في لوحة تحكم Enterprise عند التفضيل. + + + وجّه الطلبات إلى عناوين بريد محددة بناءً على أنماط الدوال أو استخراجها من حالة التدفق. + + + هيّئ استجابات احتياطية تلقائية عندما لا يرد أي شخص خلال المهلة الزمنية. + + + +### الفوائد الرئيسية + +- **مستجيبون خارجيون**: أي شخص لديه بريد إلكتروني يمكنه الاستجابة، حتى غير مستخدمي المنصة +- **تعيين ديناميكي**: استخراج بريد المُعيَّن من حالة التدفق (مثل `account_owner_email`) +- **تهيئة بسيطة**: التوجيه عبر البريد الإلكتروني أسهل في الإعداد من إدارة المستخدمين/الأدوار +- **احتياطي منشئ النشر**: إذا لم تتطابق قاعدة توجيه، يتم إخطار منشئ النشر + + +لتفاصيل التنفيذ حول مُزخرف `@human_feedback`، راجع دليل [التغذية الراجعة البشرية في التدفقات](/ar/learn/human-feedback-in-flows). + + +## إعداد سير عمل HITL القائم على Webhook + +للتكاملات المخصصة مع الأنظمة الخارجية مثل Slack وMicrosoft Teams أو تطبيقاتك الخاصة، يمكنك استخدام النهج القائم على Webhook: + + + + هيّئ مهمتك مع تفعيل الإدخال البشري: + + إدخال بشري للطاقم + + + + + عند تشغيل طاقمك، أضف رابط webhook للإدخال البشري: + + رابط Webhook للطاقم + + + + + بمجرد إتمام الطاقم للمهمة التي تتطلب إدخالاً بشرياً، ستتلقى إشعار webhook يحتوي على: + - **معرّف التنفيذ** + - **معرّف المهمة** + - **مخرجات المهمة** + + + + سيتوقف النظام في حالة `Pending Human Input`. راجع مخرجات المهمة بعناية. + + + + استدعِ نقطة نهاية الاستئناف لطاقمك بالمعلومات التالية: + + نقطة نهاية استئناف الطاقم + + + + **هام: يجب تقديم روابط Webhook مرة أخرى**: + **يجب** تقديم نفس روابط webhook (`taskWebhookUrl`، `stepWebhookUrl`، `crewWebhookUrl`) في استدعاء الاستئناف التي استخدمتها في استدعاء التشغيل. لا تُنقل تهيئات Webhook تلقائياً من التشغيل — يجب تضمينها صراحة في طلب الاستئناف لمواصلة تلقي الإشعارات لاكتمال المهام وخطوات الوكيل واكتمال الطاقم. + + + مثال على استدعاء الاستئناف مع webhooks: + ```bash + curl -X POST {BASE_URL}/resume \ + -H "Authorization: Bearer YOUR_API_TOKEN" \ + -H "Content-Type: application/json" \ + -d '{ + "execution_id": "abcd1234-5678-90ef-ghij-klmnopqrstuv", + "task_id": "research_task", + "human_feedback": "Great work! Please add more details.", + "is_approve": true, + "taskWebhookUrl": "https://your-server.com/webhooks/task", + "stepWebhookUrl": "https://your-server.com/webhooks/step", + "crewWebhookUrl": "https://your-server.com/webhooks/crew" + }' + ``` + + + **تأثير التغذية الراجعة على تنفيذ المهمة**: + من الضروري توخي الحذر عند تقديم التغذية الراجعة، حيث سيتم دمج محتوى التغذية الراجعة بالكامل كسياق إضافي لعمليات تنفيذ المهام اللاحقة. + + وهذا يعني: + - جميع المعلومات في تغذيتك الراجعة تصبح جزءاً من سياق المهمة. + - التفاصيل غير ذات الصلة قد تؤثر سلباً عليها. + - التغذية الراجعة الموجزة وذات الصلة تساعد في الحفاظ على تركيز وكفاءة المهمة. + - راجع دائماً تغذيتك الراجعة بعناية قبل الإرسال للتأكد من أنها تحتوي فقط على معلومات ذات صلة توجه تنفيذ المهمة بشكل إيجابي. + + + إذا قدمت تغذية راجعة سلبية: + - سيعيد الطاقم محاولة المهمة مع سياق إضافي من تغذيتك الراجعة. + - ستتلقى إشعار webhook آخر لمزيد من المراجعة. + - كرر الخطوات 4-6 حتى ترضى. + + + + عندما ترسل تغذية راجعة إيجابية، سيستمر التنفيذ إلى الخطوات التالية. + + + +## أفضل الممارسات + +- **كن محدداً**: قدم تغذية راجعة واضحة وقابلة للتنفيذ تعالج المهمة مباشرة +- **كن ذا صلة**: ضمّن فقط المعلومات التي ستساعد في تحسين تنفيذ المهمة +- **كن سريعاً**: استجب لمطالبات HITL بسرعة لتجنب تأخير سير العمل +- **راجع بعناية**: تحقق من تغذيتك الراجعة قبل الإرسال لضمان الدقة + +## حالات الاستخدام الشائعة + +سير عمل HITL ذو قيمة خاصة لـ: +- ضمان الجودة والتحقق +- سيناريوهات اتخاذ القرار المعقدة +- العمليات الحساسة أو عالية المخاطر +- المهام الإبداعية التي تتطلب حكماً بشرياً +- مراجعات الامتثال والتنظيم + +## اعرف المزيد + + + + استكشف قدرات منصة Enterprise الكاملة لـ Flow HITL بما في ذلك إشعارات البريد الإلكتروني وقواعد التوجيه والاستجابة التلقائية والتحليلات. + + + دليل التنفيذ لمُزخرف `@human_feedback` في تدفقاتك. + + diff --git a/docs/ar/enterprise/guides/kickoff-crew.mdx b/docs/ar/enterprise/guides/kickoff-crew.mdx new file mode 100644 index 000000000..f1e477065 --- /dev/null +++ b/docs/ar/enterprise/guides/kickoff-crew.mdx @@ -0,0 +1,178 @@ +--- +title: "تشغيل الطاقم" +description: "تشغيل طاقم على CrewAI AMP" +icon: "flag-checkered" +mode: "wide" +--- + +## نظرة عامة + +بمجرد نشر طاقمك على منصة CrewAI AMP، يمكنك بدء عمليات التنفيذ عبر واجهة الويب أو API. يغطي هذا الدليل كلا النهجين. + +## الطريقة 1: استخدام واجهة الويب + +### الخطوة 1: الانتقال إلى طاقمك المنشور + +1. سجّل الدخول إلى [CrewAI AMP](https://app.crewai.com) +2. انقر على اسم الطاقم من قائمة مشاريعك +3. ستنتقل إلى صفحة تفاصيل الطاقم + +![لوحة تحكم الطاقم](/images/enterprise/crew-dashboard.png) + +### الخطوة 2: بدء التنفيذ + +من صفحة تفاصيل طاقمك، لديك خياران لبدء التنفيذ: + +#### الخيار أ: التشغيل السريع + +1. انقر على رابط `Kickoff` في قسم Test Endpoints +2. أدخل معاملات الإدخال المطلوبة لطاقمك في محرر JSON +3. انقر على زر `Send Request` + +![نقطة نهاية التشغيل](/images/enterprise/kickoff-endpoint.png) + +#### الخيار ب: استخدام الواجهة المرئية + +1. انقر على علامة تبويب `Run` في صفحة تفاصيل الطاقم +2. أدخل المدخلات المطلوبة في حقول النموذج +3. انقر على زر `Run Crew` + +![تشغيل الطاقم](/images/enterprise/run-crew.png) + +### الخطوة 3: مراقبة تقدم التنفيذ + +بعد بدء التنفيذ: + +1. ستتلقى استجابة تحتوي على `kickoff_id` - **انسخ هذا المعرّف** +2. هذا المعرّف ضروري لتتبع تنفيذك + +![نسخ معرّف المهمة](/images/enterprise/copy-task-id.png) + +### الخطوة 4: التحقق من حالة التنفيذ + +لمراقبة تقدم تنفيذك: + +1. انقر على نقطة نهاية "Status" في قسم Test Endpoints +2. الصق `kickoff_id` في الحقل المخصص +3. انقر على زر "Get Status" + +![الحصول على الحالة](/images/enterprise/get-status.png) + +ستعرض استجابة الحالة: + +- حالة التنفيذ الحالية (`running`، `completed`، إلخ.) +- تفاصيل حول المهام الجارية +- أي مخرجات أُنتجت حتى الآن + +### الخطوة 5: عرض النتائج النهائية + +بمجرد اكتمال التنفيذ: + +1. ستتغير الحالة إلى `completed` +2. يمكنك عرض نتائج ومخرجات التنفيذ الكاملة +3. لعرض أكثر تفصيلاً، تحقق من علامة تبويب `Executions` في صفحة تفاصيل الطاقم + +## الطريقة 2: استخدام API + +يمكنك أيضاً تشغيل الطواقم برمجياً باستخدام REST API لـ CrewAI AMP. + +### المصادقة + +جميع طلبات API تتطلب رمز حامل للمصادقة: + +```bash +curl -H "Authorization: Bearer YOUR_CREW_TOKEN" https://your-crew-url.crewai.com +``` + +رمز الحامل متاح في علامة تبويب Status في صفحة تفاصيل طاقمك. + +### التحقق من صحة الطاقم + +قبل تنفيذ العمليات، يمكنك التحقق من أن طاقمك يعمل بشكل صحيح: + +```bash +curl -H "Authorization: Bearer YOUR_CREW_TOKEN" https://your-crew-url.crewai.com +``` + +ستعيد الاستجابة الناجحة رسالة تشير إلى أن الطاقم يعمل: + +``` +Healthy% +``` + +### الخطوة 1: استرداد المدخلات المطلوبة + +أولاً، حدد المدخلات التي يتطلبها طاقمك: + +```bash +curl -X GET \ + -H "Authorization: Bearer YOUR_CREW_TOKEN" \ + https://your-crew-url.crewai.com/inputs +``` + +ستكون الاستجابة كائن JSON يحتوي على مصفوفة من معاملات الإدخال المطلوبة، على سبيل المثال: + +```json +{ "inputs": ["topic", "current_year"] } +``` + +يوضح هذا المثال أن هذا الطاقم المحدد يتطلب مدخلين: `topic` و`current_year`. + +### الخطوة 2: بدء التنفيذ + +ابدأ التنفيذ بتقديم المدخلات المطلوبة: + +```bash +curl -X POST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer YOUR_CREW_TOKEN" \ + -d '{"inputs": {"topic": "AI Agent Frameworks", "current_year": "2025"}}' \ + https://your-crew-url.crewai.com/kickoff +``` + +ستتضمن الاستجابة `kickoff_id` الذي ستحتاجه للتتبع: + +```json +{ "kickoff_id": "abcd1234-5678-90ef-ghij-klmnopqrstuv" } +``` + +### الخطوة 3: التحقق من حالة التنفيذ + +راقب تقدم التنفيذ باستخدام kickoff_id: + +```bash +curl -X GET \ + -H "Authorization: Bearer YOUR_CREW_TOKEN" \ + https://your-crew-url.crewai.com/status/abcd1234-5678-90ef-ghij-klmnopqrstuv +``` + +## التعامل مع عمليات التنفيذ + +### عمليات التنفيذ طويلة المدة + +لعمليات التنفيذ التي قد تستغرق وقتاً طويلاً: + +1. فكّر في تنفيذ آلية استعلام دوري للتحقق من الحالة بشكل دوري +2. استخدم webhooks (إذا كانت متاحة) للإشعار عند اكتمال التنفيذ +3. نفّذ معالجة الأخطاء للمهلات الزمنية المحتملة + +### سياق التنفيذ + +يتضمن سياق التنفيذ: + +- المدخلات المقدمة عند التشغيل +- متغيرات البيئة المُهيأة أثناء النشر +- أي حالة محفوظة بين المهام + +### تصحيح أخطاء عمليات التنفيذ الفاشلة + +إذا فشل التنفيذ: + +1. تحقق من علامة تبويب "Executions" للسجلات المفصلة +2. راجع علامة تبويب "Traces" لتفاصيل التنفيذ خطوة بخطوة +3. ابحث عن استجابات LLM واستخدام الأدوات في تفاصيل التتبع + + + تواصل مع فريق الدعم للمساعدة في مشاكل التنفيذ أو أسئلة حول + منصة Enterprise. + diff --git a/docs/ar/enterprise/guides/microsoft-teams-trigger.mdx b/docs/ar/enterprise/guides/microsoft-teams-trigger.mdx new file mode 100644 index 000000000..5ac319d6a --- /dev/null +++ b/docs/ar/enterprise/guides/microsoft-teams-trigger.mdx @@ -0,0 +1,70 @@ +--- +title: "مشغل Microsoft Teams" +description: "تشغيل الطواقم من نشاط محادثات Microsoft Teams" +icon: "microsoft" +mode: "wide" +--- + +## نظرة عامة + +استخدم مشغل Microsoft Teams لبدء الأتمتات كلما أُنشئت محادثة جديدة. تشمل الأنماط الشائعة تلخيص الطلبات الواردة وتوجيه الرسائل العاجلة لفرق الدعم أو إنشاء مهام متابعة في أنظمة أخرى. + + + تأكد من ربط Microsoft Teams تحت **Tools & Integrations** و + تفعيله في علامة تبويب **Triggers** لعملية النشر. + + +## تفعيل مشغل Microsoft Teams + +1. افتح عملية النشر في CrewAI AMP +2. انتقل إلى علامة تبويب **Triggers** +3. حدد موقع **Microsoft Teams** وبدّل مفتاح التبديل للتفعيل + + + تفعيل أو تعطيل المشغلات بالتبديل + + +## مثال: تلخيص سلسلة محادثة جديدة + +```python +from teams_chat_created_crew import MicrosoftTeamsChatTrigger + +crew = MicrosoftTeamsChatTrigger().crew() +result = crew.kickoff({ + "crewai_trigger_payload": teams_payload, +}) +print(result.raw) +``` + +يحلل الطاقم بيانات المحادثة الوصفية (الموضوع، وقت الإنشاء، قائمة الأعضاء) وينشئ خطة عمل للفريق المستقبل. + +## الاختبار المحلي + +اختبر تكامل مشغل Microsoft Teams محلياً باستخدام CrewAI CLI: + +```bash +# عرض جميع المشغلات المتاحة +crewai triggers list + +# محاكاة مشغل Microsoft Teams بحمولة واقعية +crewai triggers run microsoft_teams/teams_message_created +``` + +سينفذ أمر `crewai triggers run` طاقمك بحمولة Teams كاملة، مما يتيح لك اختبار منطق التحليل قبل النشر. + + + استخدم `crewai triggers run microsoft_teams/teams_message_created` (وليس `crewai + run`) لمحاكاة تنفيذ المشغل أثناء التطوير. بعد النشر، سيتلقى + طاقمك حمولة المشغل تلقائياً. + + +## استكشاف الأخطاء وإصلاحها + +- تأكد من أن اتصال Teams نشط؛ يجب تحديثه إذا سحب المستأجر الصلاحيات +- اختبر محلياً بـ `crewai triggers run microsoft_teams/teams_message_created` لرؤية هيكل الحمولة بالضبط +- تأكد من أن اشتراك webhook في Microsoft 365 لا يزال صالحاً إذا توقفت الحمولات عن الوصول +- راجع سجلات التنفيذ لعدم تطابق شكل الحمولة — قد تحذف إشعارات Graph حقولاً عندما تكون المحادثة خاصة أو مقيدة +- تذكر: استخدم `crewai triggers run` (وليس `crewai run`) لمحاكاة تنفيذ المشغل diff --git a/docs/ar/enterprise/guides/onedrive-trigger.mdx b/docs/ar/enterprise/guides/onedrive-trigger.mdx new file mode 100644 index 000000000..ef9fd0c40 --- /dev/null +++ b/docs/ar/enterprise/guides/onedrive-trigger.mdx @@ -0,0 +1,69 @@ +--- +title: "مشغل OneDrive" +description: "أتمتة الاستجابات لنشاط ملفات OneDrive" +icon: "cloud" +mode: "wide" +--- + +## نظرة عامة + +ابدأ الأتمتات عند تغيير الملفات داخل OneDrive. يمكنك إنشاء ملخصات تدقيق وإخطار فرق الأمان بشأن المشاركة الخارجية أو تحديث أنظمة الأعمال اللاحقة ببيانات المستندات الوصفية الجديدة. + + + اربط OneDrive في **Tools & Integrations** وبدّل المشغل لعملية + النشر. + + +## تفعيل مشغل OneDrive + +1. افتح عملية النشر في CrewAI AMP +2. انتقل إلى علامة تبويب **Triggers** +3. حدد موقع **OneDrive** وبدّل مفتاح التبديل للتفعيل + + + تفعيل أو تعطيل المشغلات بالتبديل + + +## مثال: تدقيق صلاحيات الملفات + +```python +from onedrive_file_crew import OneDriveFileTrigger + +crew = OneDriveFileTrigger().crew() +crew.kickoff({ + "crewai_trigger_payload": onedrive_payload, +}) +``` + +يفحص الطاقم بيانات الملف الوصفية ونشاط المستخدم وتغييرات الصلاحيات لإنتاج ملخص متوافق مع متطلبات الامتثال. + +## الاختبار المحلي + +اختبر تكامل مشغل OneDrive محلياً باستخدام CrewAI CLI: + +```bash +# عرض جميع المشغلات المتاحة +crewai triggers list + +# محاكاة مشغل OneDrive بحمولة واقعية +crewai triggers run microsoft_onedrive/file_changed +``` + +سينفذ أمر `crewai triggers run` طاقمك بحمولة OneDrive كاملة، مما يتيح لك اختبار منطق التحليل قبل النشر. + + + استخدم `crewai triggers run microsoft_onedrive/file_changed` (وليس `crewai run`) + لمحاكاة تنفيذ المشغل أثناء التطوير. بعد النشر، سيتلقى طاقمك + حمولة المشغل تلقائياً. + + +## استكشاف الأخطاء وإصلاحها + +- تأكد من أن الحساب المتصل لديه صلاحية قراءة بيانات الملف الوصفية المضمنة في webhook +- اختبر محلياً بـ `crewai triggers run microsoft_onedrive/file_changed` لرؤية هيكل الحمولة بالضبط +- إذا كان المشغل يعمل لكن الحمولة تفتقد `permissions`، تأكد من أن إعدادات المشاركة على مستوى الموقع تسمح لـ Graph بإرجاع هذا الحقل +- للمستأجرين الكبار، صفّ الإشعارات مسبقاً حتى يعمل الطاقم فقط على المجلدات ذات الصلة +- تذكر: استخدم `crewai triggers run` (وليس `crewai run`) لمحاكاة تنفيذ المشغل diff --git a/docs/ar/enterprise/guides/outlook-trigger.mdx b/docs/ar/enterprise/guides/outlook-trigger.mdx new file mode 100644 index 000000000..9fa320bc9 --- /dev/null +++ b/docs/ar/enterprise/guides/outlook-trigger.mdx @@ -0,0 +1,69 @@ +--- +title: "مشغل Outlook" +description: "إطلاق الأتمتات من رسائل Outlook وتحديثات التقويم" +icon: "microsoft" +mode: "wide" +--- + +## نظرة عامة + +أتمت الاستجابات عندما يسلّم Outlook رسالة جديدة أو عند إزالة حدث من التقويم. تقوم الفرق عادة بتوجيه التصعيدات وإنشاء تذاكر أو تنبيه الحاضرين بالإلغاءات. + + + اربط Outlook في **Tools & Integrations** وتأكد من تفعيل المشغل + لعملية النشر. + + +## تفعيل مشغل Outlook + +1. افتح عملية النشر في CrewAI AMP +2. انتقل إلى علامة تبويب **Triggers** +3. حدد موقع **Outlook** وبدّل مفتاح التبديل للتفعيل + + + تفعيل أو تعطيل المشغلات بالتبديل + + +## مثال: تلخيص رسالة بريد إلكتروني جديدة + +```python +from outlook_message_crew import OutlookMessageTrigger + +crew = OutlookMessageTrigger().crew() +crew.kickoff({ + "crewai_trigger_payload": outlook_payload, +}) +``` + +يستخرج الطاقم تفاصيل المرسل والموضوع ومعاينة النص والمرفقات قبل إنشاء استجابة منظمة. + +## الاختبار المحلي + +اختبر تكامل مشغل Outlook محلياً باستخدام CrewAI CLI: + +```bash +# عرض جميع المشغلات المتاحة +crewai triggers list + +# محاكاة مشغل Outlook بحمولة واقعية +crewai triggers run microsoft_outlook/email_received +``` + +سينفذ أمر `crewai triggers run` طاقمك بحمولة Outlook كاملة، مما يتيح لك اختبار منطق التحليل قبل النشر. + + + استخدم `crewai triggers run microsoft_outlook/email_received` (وليس `crewai run`) + لمحاكاة تنفيذ المشغل أثناء التطوير. بعد النشر، سيتلقى طاقمك + حمولة المشغل تلقائياً. + + +## استكشاف الأخطاء وإصلاحها + +- تحقق من أن موصل Outlook لا يزال مفوّضاً؛ يجب تجديد الاشتراك دورياً +- اختبر محلياً بـ `crewai triggers run microsoft_outlook/email_received` لرؤية هيكل الحمولة بالضبط +- إذا كانت المرفقات مفقودة، تأكد من أن اشتراك webhook يتضمن علامة `includeResourceData` +- راجع سجلات التنفيذ عندما تفشل الأحداث في المطابقة — حمولات الإلغاء تفتقد قوائم الحاضرين حسب التصميم ويجب أن يأخذ الطاقم ذلك في الاعتبار +- تذكر: استخدم `crewai triggers run` (وليس `crewai run`) لمحاكاة تنفيذ المشغل diff --git a/docs/ar/enterprise/guides/prepare-for-deployment.mdx b/docs/ar/enterprise/guides/prepare-for-deployment.mdx new file mode 100644 index 000000000..37ebe8ed0 --- /dev/null +++ b/docs/ar/enterprise/guides/prepare-for-deployment.mdx @@ -0,0 +1,311 @@ +--- +title: "التحضير للنشر" +description: "تأكد من جاهزية طاقمك أو تدفقك للنشر على CrewAI AMP" +icon: "clipboard-check" +mode: "wide" +--- + + + قبل النشر على CrewAI AMP، من الضروري التحقق من صحة بنية مشروعك. + يمكن نشر كل من الطواقم والتدفقات كـ "أتمتات"، لكن لهما بنى مشاريع + ومتطلبات مختلفة يجب استيفاؤها لنجاح النشر. + + +## فهم الأتمتات + +في CrewAI AMP، **الأتمتات** هو المصطلح الشامل لمشاريع الذكاء الاصطناعي الوكيل القابلة للنشر. يمكن أن تكون الأتمتة إما: + +- **طاقم**: فريق مستقل من وكلاء الذكاء الاصطناعي يعملون معاً على المهام +- **تدفق**: سير عمل مُنسّق يمكنه الجمع بين طواقم متعددة واستدعاءات LLM المباشرة والمنطق الإجرائي + +فهم النوع الذي تنشره ضروري لأن لهما بنى مشاريع ونقاط دخول مختلفة. + +## الطواقم مقابل التدفقات: الفروقات الرئيسية + + + + فرق وكلاء ذكاء اصطناعي مستقلة مع `crew.py` يحدد الوكلاء والمهام. الأفضل للمهام المركزة والتعاونية. + + + سير عمل مُنسّق مع طواقم مضمنة في مجلد `crews/`. الأفضل للعمليات المعقدة متعددة المراحل. + + + +| الجانب | الطاقم | التدفق | +|--------|--------|--------| +| **بنية المشروع** | `src/project_name/` مع `crew.py` | `src/project_name/` مع مجلد `crews/` | +| **موقع المنطق الرئيسي** | `src/project_name/crew.py` | `src/project_name/main.py` (فئة Flow) | +| **دالة نقطة الدخول** | `run()` في `main.py` | `kickoff()` في `main.py` | +| **نوع pyproject.toml** | `type = "crew"` | `type = "flow"` | +| **أمر CLI للإنشاء** | `crewai create crew name` | `crewai create flow name` | +| **موقع التهيئة** | `src/project_name/config/` | `src/project_name/crews/crew_name/config/` | +| **يمكن أن يحتوي طواقم أخرى** | لا | نعم (في مجلد `crews/`) | + +## مرجع بنية المشروع + +### بنية مشروع الطاقم + +عند تشغيل `crewai create crew my_crew`، تحصل على هذه البنية: + +``` +my_crew/ +├── .gitignore +├── pyproject.toml # Must have type = "crew" +├── README.md +├── .env +├── uv.lock # REQUIRED for deployment +└── src/ + └── my_crew/ + ├── __init__.py + ├── main.py # Entry point with run() function + ├── crew.py # Crew class with @CrewBase decorator + ├── tools/ + │ ├── custom_tool.py + │ └── __init__.py + └── config/ + ├── agents.yaml # Agent definitions + └── tasks.yaml # Task definitions +``` + + + بنية `src/project_name/` المتداخلة ضرورية للطواقم. + وضع الملفات في المستوى الخاطئ سيسبب فشل النشر. + + +### بنية مشروع التدفق + +عند تشغيل `crewai create flow my_flow`، تحصل على هذه البنية: + +``` +my_flow/ +├── .gitignore +├── pyproject.toml # Must have type = "flow" +├── README.md +├── .env +├── uv.lock # REQUIRED for deployment +└── src/ + └── my_flow/ + ├── __init__.py + ├── main.py # Entry point with kickoff() function + Flow class + ├── crews/ # Embedded crews folder + │ └── poem_crew/ + │ ├── __init__.py + │ ├── poem_crew.py # Crew with @CrewBase decorator + │ └── config/ + │ ├── agents.yaml + │ └── tasks.yaml + └── tools/ + ├── __init__.py + └── custom_tool.py +``` + + + كلا الطواقم والتدفقات تستخدم بنية `src/project_name/`. + الفرق الرئيسي أن التدفقات لها مجلد `crews/` للطواقم المضمنة، + بينما الطواقم لها `crew.py` مباشرة في مجلد المشروع. + + +## قائمة فحص ما قبل النشر + +استخدم هذه القائمة للتحقق من جاهزية مشروعك للنشر. + +### 1. التحقق من تهيئة pyproject.toml + +يجب أن يتضمن `pyproject.toml` قسم `[tool.crewai]` الصحيح: + + + + ```toml + [tool.crewai] + type = "crew" + ``` + + + ```toml + [tool.crewai] + type = "flow" + ``` + + + + + إذا لم يتطابق `type` مع بنية مشروعك، سيفشل البناء أو + لن تعمل الأتمتة بشكل صحيح. + + +### 2. التأكد من وجود ملف uv.lock + +يستخدم CrewAI `uv` لإدارة الاعتماديات. يضمن ملف `uv.lock` بناءً قابلاً للتكرار وهو **مطلوب** للنشر. + +```bash +# إنشاء أو تحديث ملف القفل +uv lock + +# التحقق من وجوده +ls -la uv.lock +``` + +إذا لم يكن الملف موجوداً، شغّل `uv lock` وارفعه إلى مستودعك: + +```bash +uv lock +git add uv.lock +git commit -m "Add uv.lock for deployment" +git push +``` + +### 3. التحقق من استخدام مُزخرف CrewBase + +**يجب أن تستخدم كل فئة طاقم مُزخرف `@CrewBase`.** ينطبق هذا على: + +- مشاريع الطاقم المستقلة +- الطواقم المضمنة داخل مشاريع التدفق + +```python +from crewai import Agent, Crew, Process, Task +from crewai.project import CrewBase, agent, crew, task +from crewai.agents.agent_builder.base_agent import BaseAgent +from typing import List + +@CrewBase # This decorator is REQUIRED +class MyCrew(): + """My crew description""" + + agents: List[BaseAgent] + tasks: List[Task] + + @agent + def my_agent(self) -> Agent: + return Agent( + config=self.agents_config['my_agent'], # type: ignore[index] + verbose=True + ) + + @task + def my_task(self) -> Task: + return Task( + config=self.tasks_config['my_task'] # type: ignore[index] + ) + + @crew + def crew(self) -> Crew: + return Crew( + agents=self.agents, + tasks=self.tasks, + process=Process.sequential, + verbose=True, + ) +``` + + + إذا نسيت مُزخرف `@CrewBase`، سيفشل النشر بأخطاء حول + تهيئات الوكلاء أو المهام المفقودة. + + +### 4. التحقق من نقاط دخول المشروع + +كل من الطواقم والتدفقات لها نقطة دخول في `src/project_name/main.py`: + + + + تستخدم نقطة الدخول دالة `run()`: + + ```python + # src/my_crew/main.py + from my_crew.crew import MyCrew + + def run(): + """Run the crew.""" + inputs = {'topic': 'AI in Healthcare'} + result = MyCrew().crew().kickoff(inputs=inputs) + return result + + if __name__ == "__main__": + run() + ``` + + + تستخدم نقطة الدخول دالة `kickoff()` مع فئة Flow: + + ```python + # src/my_flow/main.py + from crewai.flow import Flow, listen, start + from my_flow.crews.poem_crew.poem_crew import PoemCrew + + class MyFlow(Flow): + @start() + def begin(self): + # Flow logic here + result = PoemCrew().crew().kickoff(inputs={...}) + return result + + def kickoff(): + """Run the flow.""" + MyFlow().kickoff() + + if __name__ == "__main__": + kickoff() + ``` + + + +### 5. تحضير متغيرات البيئة + +قبل النشر، تأكد من أن لديك: + +1. **مفاتيح API لـ LLM** جاهزة (OpenAI، Anthropic، Google، إلخ.) +2. **مفاتيح API للأدوات** إذا كنت تستخدم أدوات خارجية (Serper، إلخ.) + + + إذا كان مشروعك يعتمد على حزم من **سجل PyPI خاص**، ستحتاج أيضاً لتهيئة + بيانات اعتماد مصادقة السجل كمتغيرات بيئة. راجع + دليل [سجلات الحزم الخاصة](/ar/enterprise/guides/private-package-registry) للتفاصيل. + + + + اختبر مشروعك محلياً بنفس متغيرات البيئة قبل النشر + لاكتشاف مشاكل التهيئة مبكراً. + + +## أوامر التحقق السريع + +شغّل هذه الأوامر من جذر مشروعك للتحقق السريع من إعدادك: + +```bash +# 1. Check project type in pyproject.toml +grep -A2 "\[tool.crewai\]" pyproject.toml + +# 2. Verify uv.lock exists +ls -la uv.lock || echo "ERROR: uv.lock missing! Run 'uv lock'" + +# 3. Verify src/ structure exists +ls -la src/*/main.py 2>/dev/null || echo "No main.py found in src/" + +# 4. For Crews - verify crew.py exists +ls -la src/*/crew.py 2>/dev/null || echo "No crew.py (expected for Crews)" + +# 5. For Flows - verify crews/ folder exists +ls -la src/*/crews/ 2>/dev/null || echo "No crews/ folder (expected for Flows)" + +# 6. Check for CrewBase usage +grep -r "@CrewBase" . --include="*.py" +``` + +## أخطاء الإعداد الشائعة + +| الخطأ | العرض | الإصلاح | +|-------|-------|---------| +| `uv.lock` مفقود | فشل البناء أثناء حل الاعتماديات | شغّل `uv lock` وارفعه | +| `type` خاطئ في pyproject.toml | نجاح البناء لكن فشل وقت التشغيل | غيّر إلى النوع الصحيح | +| مُزخرف `@CrewBase` مفقود | أخطاء "Config not found" | أضف المُزخرف لجميع فئات الطاقم | +| ملفات في الجذر بدل `src/` | نقطة الدخول غير موجودة | انقلها إلى `src/project_name/` | +| `run()` أو `kickoff()` مفقودة | لا يمكن بدء الأتمتة | أضف دالة الدخول الصحيحة | + +## الخطوات التالية + +بمجرد اجتياز مشروعك لجميع عناصر القائمة، أنت جاهز للنشر: + + + اتبع دليل النشر لنشر طاقمك أو تدفقك على CrewAI AMP باستخدام + CLI أو واجهة الويب أو تكامل CI/CD. + diff --git a/docs/ar/enterprise/guides/private-package-registry.mdx b/docs/ar/enterprise/guides/private-package-registry.mdx new file mode 100644 index 000000000..d9633ff0c --- /dev/null +++ b/docs/ar/enterprise/guides/private-package-registry.mdx @@ -0,0 +1,263 @@ +--- +title: "سجلات الحزم الخاصة" +description: "تثبيت حزم Python الخاصة من سجلات PyPI المصادق عليها في CrewAI AMP" +icon: "lock" +mode: "wide" +--- + + + يغطي هذا الدليل كيفية تهيئة مشروع CrewAI لتثبيت حزم Python + من سجلات PyPI الخاصة (Azure DevOps Artifacts، GitHub Packages، GitLab، AWS CodeArtifact، إلخ.) + عند النشر على CrewAI AMP. + + +## متى تحتاج هذا + +إذا كان مشروعك يعتمد على حزم Python داخلية أو خاصة مستضافة على سجل خاص +بدلاً من PyPI العام، ستحتاج إلى: + +1. إخبار UV **أين** يجد الحزمة (رابط فهرس) +2. إخبار UV **أي** حزم تأتي من ذلك الفهرس (تعيين مصدر) +3. تقديم **بيانات اعتماد** حتى يتمكن UV من المصادقة أثناء التثبيت + +يستخدم CrewAI AMP [UV](https://docs.astral.sh/uv/) لحل وتثبيت الاعتماديات. +يدعم UV السجلات الخاصة المصادق عليها عبر تهيئة `pyproject.toml` مع +متغيرات بيئة لبيانات الاعتماد. + +## الخطوة 1: تهيئة pyproject.toml + +ثلاثة أجزاء تعمل معاً في `pyproject.toml`: + +### 1أ. التصريح بالاعتمادية + +أضف الحزمة الخاصة إلى `[project.dependencies]` كأي اعتمادية أخرى: + +```toml +[project] +dependencies = [ + "crewai[tools]>=0.100.1,<1.0.0", + "my-private-package>=1.2.0", +] +``` + +### 1ب. تعريف الفهرس + +سجّل سجلك الخاص كفهرس مسمّى تحت `[[tool.uv.index]]`: + +```toml +[[tool.uv.index]] +name = "my-private-registry" +url = "https://pkgs.dev.azure.com/my-org/_packaging/my-feed/pypi/simple/" +explicit = true +``` + + + حقل `name` مهم — يستخدمه UV لبناء أسماء متغيرات البيئة + للمصادقة (راجع [الخطوة 2](#step-2-set-authentication-credentials) أدناه). + + تعيين `explicit = true` يعني أن UV لن يبحث في هذا الفهرس عن كل حزمة — فقط + الحزم التي تعيّنها صراحة له في `[tool.uv.sources]`. يتجنب ذلك الاستعلامات غير الضرورية + ضد سجلك الخاص ويحمي من هجمات ارتباك الاعتماديات. + + +### 1ج. تعيين الحزمة للفهرس + +أخبر UV أي حزم يجب حلها من فهرسك الخاص باستخدام `[tool.uv.sources]`: + +```toml +[tool.uv.sources] +my-private-package = { index = "my-private-registry" } +``` + +### مثال كامل + +```toml +[project] +name = "my-crew-project" +version = "0.1.0" +requires-python = ">=3.10,<=3.13" +dependencies = [ + "crewai[tools]>=0.100.1,<1.0.0", + "my-private-package>=1.2.0", +] + +[tool.crewai] +type = "crew" + +[[tool.uv.index]] +name = "my-private-registry" +url = "https://pkgs.dev.azure.com/my-org/_packaging/my-feed/pypi/simple/" +explicit = true + +[tool.uv.sources] +my-private-package = { index = "my-private-registry" } +``` + +بعد تحديث `pyproject.toml`، أعد إنشاء ملف القفل: + +```bash +uv lock +``` + + + ارفع دائماً `uv.lock` المُحدّث مع تغييرات `pyproject.toml`. + ملف القفل مطلوب للنشر — راجع [التحضير للنشر](/ar/enterprise/guides/prepare-for-deployment). + + +## الخطوة 2: تعيين بيانات اعتماد المصادقة + +يصادق UV ضد الفهارس الخاصة باستخدام متغيرات بيئة تتبع اصطلاح تسمية +بناءً على اسم الفهرس الذي حددته في `pyproject.toml`: + +``` +UV_INDEX_{UPPER_NAME}_USERNAME +UV_INDEX_{UPPER_NAME}_PASSWORD +``` + +حيث `{UPPER_NAME}` هو اسم فهرسك محوّلاً إلى **أحرف كبيرة** مع **استبدال الشرطات بشرطات سفلية**. + +على سبيل المثال، فهرس باسم `my-private-registry` يستخدم: + +| المتغير | القيمة | +|---------|--------| +| `UV_INDEX_MY_PRIVATE_REGISTRY_USERNAME` | اسم مستخدم السجل أو اسم الرمز | +| `UV_INDEX_MY_PRIVATE_REGISTRY_PASSWORD` | كلمة مرور السجل أو الرمز/PAT | + + + هذه المتغيرات **يجب** إضافتها عبر إعدادات **Environment Variables** في CrewAI AMP — + إما عالمياً أو على مستوى النشر. لا يمكن تعيينها في ملفات `.env` أو ترميزها في مشروعك. + + راجع [تعيين متغيرات البيئة في AMP](#setting-environment-variables-in-amp) أدناه. + + +## مرجع مزودي السجلات + +يوضح الجدول أدناه تنسيق رابط الفهرس وقيم بيانات الاعتماد لمزودي السجلات الشائعين. +استبدل القيم المؤقتة بتفاصيل مؤسستك وخلاصتك الفعلية. + +| المزود | رابط الفهرس | اسم المستخدم | كلمة المرور | +|--------|-------------|--------------|-------------| +| **Azure DevOps Artifacts** | `https://pkgs.dev.azure.com/{org}/_packaging/{feed}/pypi/simple/` | أي نص غير فارغ (مثل `token`) | Personal Access Token (PAT) بنطاق Packaging Read | +| **GitHub Packages** | `https://pypi.pkg.github.com/{owner}/simple/` | اسم مستخدم GitHub | Personal Access Token (classic) بنطاق `read:packages` | +| **GitLab Package Registry** | `https://gitlab.com/api/v4/projects/{project_id}/packages/pypi/simple/` | `__token__` | Project أو Personal Access Token بنطاق `read_api` | +| **AWS CodeArtifact** | استخدم الرابط من `aws codeartifact get-repository-endpoint` | `aws` | رمز من `aws codeartifact get-authorization-token` | +| **Google Artifact Registry** | `https://{region}-python.pkg.dev/{project}/{repo}/simple/` | `_json_key_base64` | مفتاح حساب الخدمة بتشفير Base64 | +| **JFrog Artifactory** | `https://{instance}.jfrog.io/artifactory/api/pypi/{repo}/simple/` | اسم المستخدم أو البريد الإلكتروني | مفتاح API أو رمز الهوية | +| **مستضاف ذاتياً (devpi، Nexus، إلخ.)** | رابط Simple API لسجلك | اسم مستخدم السجل | كلمة مرور السجل | + + + لـ **AWS CodeArtifact**، تنتهي صلاحية رمز التفويض دورياً. + ستحتاج لتحديث قيمة `UV_INDEX_*_PASSWORD` عند انتهاء صلاحيتها. + فكّر في أتمتة هذا في خط أنابيب CI/CD. + + +## تعيين متغيرات البيئة في AMP + +يجب تهيئة بيانات اعتماد السجل الخاص كمتغيرات بيئة في CrewAI AMP. +لديك خياران: + + + + 1. سجّل الدخول إلى [CrewAI AMP](https://app.crewai.com) + 2. انتقل إلى أتمتتك + 3. افتح علامة تبويب **Environment Variables** + 4. أضف كل متغير (`UV_INDEX_*_USERNAME` و`UV_INDEX_*_PASSWORD`) مع قيمته + + راجع خطوة [النشر على AMP — تعيين متغيرات البيئة](/ar/enterprise/guides/deploy-to-amp#set-environment-variables) للتفاصيل. + + + أضف المتغيرات إلى ملف `.env` المحلي قبل تشغيل `crewai deploy create`. + سينقلها CLI بأمان إلى المنصة: + + ```bash + # .env + OPENAI_API_KEY=sk-... + UV_INDEX_MY_PRIVATE_REGISTRY_USERNAME=token + UV_INDEX_MY_PRIVATE_REGISTRY_PASSWORD=your-pat-here + ``` + + ```bash + crewai deploy create + ``` + + + + + **لا ترفع** أبداً بيانات الاعتماد إلى مستودعك. استخدم متغيرات بيئة AMP لجميع الأسرار. + يجب إدراج ملف `.env` في `.gitignore`. + + +لتحديث بيانات الاعتماد في نشر حالي، راجع [تحديث طاقمك — متغيرات البيئة](/ar/enterprise/guides/update-crew). + +## كيف يعمل الكل معاً + +عندما يبني CrewAI AMP أتمتتك، يعمل تدفق الحل هكذا: + + + + يسحب AMP مستودعك ويقرأ `pyproject.toml` و`uv.lock`. + + + يقرأ UV `[tool.uv.sources]` لتحديد أي فهرس يجب أن تأتي منه كل حزمة. + + + لكل فهرس خاص، يبحث UV عن `UV_INDEX_{NAME}_USERNAME` و`UV_INDEX_{NAME}_PASSWORD` + من متغيرات البيئة التي هيأتها في AMP. + + + يحمّل UV ويثبّت جميع الحزم — العامة (من PyPI) والخاصة (من سجلك). + + + يبدأ طاقمك أو تدفقك مع توفر جميع الاعتماديات. + + + +## استكشاف الأخطاء وإصلاحها + +### أخطاء المصادقة أثناء البناء + +**العرض**: فشل البناء بـ `401 Unauthorized` أو `403 Forbidden` عند حل حزمة خاصة. + +**تحقق من**: +- أسماء متغيرات البيئة `UV_INDEX_*` تتطابق مع اسم فهرسك بالضبط (أحرف كبيرة، شرطات → شرطات سفلية) +- بيانات الاعتماد معيّنة في متغيرات بيئة AMP، وليس فقط في `.env` محلي +- الرمز/PAT لديه صلاحيات القراءة المطلوبة لخلاصة الحزم +- الرمز لم تنتهِ صلاحيته (ذو صلة خاصة لـ AWS CodeArtifact) + +### الحزمة غير موجودة + +**العرض**: `No matching distribution found for my-private-package`. + +**تحقق من**: +- رابط الفهرس في `pyproject.toml` ينتهي بـ `/simple/` +- إدخال `[tool.uv.sources]` يعيّن اسم الحزمة الصحيح لاسم الفهرس الصحيح +- الحزمة منشورة فعلاً في سجلك الخاص +- شغّل `uv lock` محلياً بنفس بيانات الاعتماد للتحقق من عمل الحل + +### تعارضات ملف القفل + +**العرض**: فشل `uv lock` أو نتائج غير متوقعة بعد إضافة فهرس خاص. + +**الحل**: عيّن بيانات الاعتماد محلياً وأعد الإنشاء: + +```bash +export UV_INDEX_MY_PRIVATE_REGISTRY_USERNAME=token +export UV_INDEX_MY_PRIVATE_REGISTRY_PASSWORD=your-pat +uv lock +``` + +ثم ارفع `uv.lock` المُحدّث. + +## أدلة ذات صلة + + + + تحقق من بنية المشروع والاعتماديات قبل النشر. + + + انشر طاقمك أو تدفقك وهيّئ متغيرات البيئة. + + + حدّث متغيرات البيئة وادفع التغييرات إلى نشر قائم. + + diff --git a/docs/ar/enterprise/guides/react-component-export.mdx b/docs/ar/enterprise/guides/react-component-export.mdx new file mode 100644 index 000000000..d1ec9d362 --- /dev/null +++ b/docs/ar/enterprise/guides/react-component-export.mdx @@ -0,0 +1,112 @@ +--- +title: "تصدير مكون React" +description: "تعلم كيفية تصدير ودمج مكونات React من CrewAI AMP في تطبيقاتك" +icon: "react" +mode: "wide" +--- + +يشرح هذا الدليل كيفية تصدير طواقم CrewAI AMP كمكونات React ودمجها في تطبيقاتك. + +## تصدير مكون React + + + + انقر على القائمة (ثلاث نقاط على يمين طاقمك المنشور) واختر خيار التصدير واحفظ الملف محلياً. سنستخدم `CrewLead.jsx` في مثالنا. + + + تصدير مكون React + + + + + +## إعداد بيئة React + +لتشغيل مكون React هذا محلياً، ستحتاج لإعداد بيئة تطوير React ودمج هذا المكون في مشروع React. + + + + - حمّل وثبّت Node.js من الموقع الرسمي: https://nodejs.org/ + - اختر إصدار LTS (الدعم طويل المدى) للاستقرار. + + + + - افتح Command Prompt أو PowerShell + - انتقل إلى المجلد الذي تريد إنشاء مشروعك فيه + - شغّل الأمر التالي لإنشاء مشروع React جديد: + + ```bash + npx create-react-app my-crew-app + ``` + - انتقل إلى مجلد المشروع: + + ```bash + cd my-crew-app + ``` + + + + ```bash + npm install react-dom + ``` + + + + - انقل الملف المُحمّل `CrewLead.jsx` إلى مجلد `src` في مشروعك. + + + + - افتح `src/App.js` + - استبدل محتوياته بشيء مثل هذا: + + ```jsx + import React from 'react'; + import CrewLead from './CrewLead'; + + function App() { + return ( +
+ +
+ ); + } + + export default App; + ``` + - استبدل `YOUR_API_BASE_URL` و`YOUR_BEARER_TOKEN` بالقيم الفعلية لـ API. + + + + - في مجلد مشروعك، شغّل: + + ```bash + npm start + ``` + - سيبدأ خادم التطوير، ويجب أن يفتح متصفح الويب الافتراضي تلقائياً على `http://localhost:3000`، حيث سترى تطبيق React يعمل. + + + + +## التخصيص + +يمكنك بعد ذلك تخصيص `CrewLead.jsx` لإضافة اللون والعنوان وغيرها. + + + تخصيص مكون React + + + تخصيص مكون React + + +## الخطوات التالية + +- خصّص تنسيق المكون ليتوافق مع تصميم تطبيقك +- أضف خصائص إضافية للتهيئة +- ادمج مع إدارة حالة تطبيقك +- أضف معالجة الأخطاء وحالات التحميل diff --git a/docs/ar/enterprise/guides/salesforce-trigger.mdx b/docs/ar/enterprise/guides/salesforce-trigger.mdx new file mode 100644 index 000000000..8cd16c026 --- /dev/null +++ b/docs/ar/enterprise/guides/salesforce-trigger.mdx @@ -0,0 +1,50 @@ +--- +title: "مشغل Salesforce" +description: "تشغيل طواقم CrewAI من سير عمل Salesforce لأتمتة CRM" +icon: "salesforce" +mode: "wide" +--- + +يمكن تشغيل CrewAI AMP من Salesforce لأتمتة سير عمل إدارة علاقات العملاء وتعزيز عمليات المبيعات. + +## نظرة عامة + +Salesforce هي منصة رائدة لإدارة علاقات العملاء (CRM) تساعد الشركات على تبسيط عمليات المبيعات والخدمة والتسويق. من خلال إعداد مشغلات CrewAI من Salesforce، يمكنك: + +- أتمتة تسجيل وتأهيل العملاء المحتملين +- إنشاء مواد مبيعات مخصصة +- تعزيز خدمة العملاء بردود مدعومة بالذكاء الاصطناعي +- تبسيط تحليل البيانات وإعداد التقارير + +## عرض توضيحي + + + +## البدء + +لإعداد مشغلات Salesforce: + +1. **تواصل مع الدعم**: تواصل مع دعم CrewAI AMP للمساعدة في إعداد مشغل Salesforce +2. **مراجعة المتطلبات**: تأكد من أن لديك صلاحيات Salesforce اللازمة والوصول إلى API +3. **تهيئة الاتصال**: اعمل مع فريق الدعم لإنشاء الاتصال بين CrewAI ومثيل Salesforce الخاص بك +4. **اختبار المشغلات**: تحقق من عمل المشغلات بشكل صحيح مع حالات الاستخدام المحددة + +## حالات الاستخدام + +سيناريوهات Salesforce + CrewAI الشائعة تشمل: + +- **معالجة العملاء المحتملين**: تحليل وتسجيل العملاء المحتملين الوافدين تلقائياً +- **إنشاء العروض**: إنشاء عروض مخصصة بناءً على بيانات الفرص +- **رؤى العملاء**: إنشاء تقارير تحليلية من سجل تفاعلات العملاء +- **أتمتة المتابعة**: إنشاء رسائل متابعة وتوصيات مخصصة + +## الخطوات التالية + +للحصول على تعليمات الإعداد المفصلة وخيارات التهيئة المتقدمة، يرجى التواصل مع دعم CrewAI AMP الذي يمكنه تقديم إرشادات مخصصة لبيئة Salesforce واحتياجات عملك المحددة. diff --git a/docs/ar/enterprise/guides/slack-trigger.mdx b/docs/ar/enterprise/guides/slack-trigger.mdx new file mode 100644 index 000000000..28aed7b6e --- /dev/null +++ b/docs/ar/enterprise/guides/slack-trigger.mdx @@ -0,0 +1,62 @@ +--- +title: "مشغل Slack" +description: "تشغيل طواقم CrewAI مباشرة من Slack باستخدام أوامر الشرطة المائلة" +icon: "slack" +mode: "wide" +--- + +يشرح هذا الدليل كيفية بدء طاقم مباشرة من Slack باستخدام مشغلات CrewAI. + +## المتطلبات المسبقة + +- مشغل CrewAI لـ Slack مُثبّت ومتصل بمساحة عمل Slack +- طاقم واحد على الأقل مُهيأ في CrewAI + +## خطوات الإعداد + + + + في لوحة تحكم CrewAI، انتقل إلى قسم **Triggers**. + + + تكامل CrewAI مع Slack + + + تحقق من أن Slack مدرج ومتصل. + + + - انتقل إلى القناة التي تريد تشغيل الطاقم منها. + - اكتب أمر الشرطة المائلة "**/kickoff**" لبدء عملية تشغيل الطاقم. + - يجب أن ترى "**Kickoff crew**" تظهر أثناء الكتابة: + + تشغيل الطاقم + + - اضغط Enter أو اختر خيار "**Kickoff crew**". سيظهر مربع حوار بعنوان "**Kickoff an AI Crew**". + + + - في القائمة المنسدلة "**Select of the crews online:**"، اختر الطاقم الذي تريد بدءه. + - في المثال أدناه، تم اختيار "**prep-for-meeting**": + + القائمة المنسدلة لتشغيل الطاقم + + - إذا كان طاقمك يتطلب أي مدخلات، انقر على زر "**Add Inputs**" لتقديمها. + + زر "**Add Inputs**" معروض في المثال أعلاه لكن لم يُنقر عليه بعد. + + + + - بمجرد اختيار الطاقم وإضافة أي مدخلات ضرورية، انقر على "**Kickoff**" لبدء الطاقم. + + تشغيل الطاقم + + - سيبدأ الطاقم بالتنفيذ وسترى النتائج في قناة Slack. + + نتائج تشغيل الطاقم + + + + +## نصائح + +- تأكد من أن لديك الصلاحيات اللازمة لاستخدام أمر `/kickoff` في مساحة عمل Slack. +- إذا لم تر الطاقم المطلوب في القائمة المنسدلة، تأكد من أنه مُهيأ بشكل صحيح ومتصل في CrewAI. diff --git a/docs/ar/enterprise/guides/team-management.mdx b/docs/ar/enterprise/guides/team-management.mdx new file mode 100644 index 000000000..7381958e4 --- /dev/null +++ b/docs/ar/enterprise/guides/team-management.mdx @@ -0,0 +1,91 @@ +--- +title: "إدارة الفريق" +description: "تعلم كيفية دعوة وإدارة أعضاء الفريق في مؤسسة CrewAI AMP" +icon: "users" +mode: "wide" +--- + +بصفتك مسؤولاً عن حساب CrewAI AMP، يمكنك بسهولة دعوة أعضاء جدد للانضمام إلى مؤسستك. يرشدك هذا الدليل خلال العملية خطوة بخطوة. + +## دعوة أعضاء الفريق + + + + - سجّل الدخول إلى حساب CrewAI AMP - ابحث عن أيقونة الترس في + الزاوية العلوية اليمنى من لوحة التحكم - انقر على أيقونة الترس للوصول إلى + صفحة **Settings**: + + صفحة الإعدادات + + + + - في صفحة الإعدادات، سترى علامة تبويب `Members` - انقر على علامة تبويب `Members` + للوصول إلى صفحة **Members**: + + علامة تبويب الأعضاء + + + + - في قسم الأعضاء، سترى قائمة بالأعضاء الحاليين (بما فيهم + أنت) - حدد موقع حقل إدخال `Email` - أدخل عنوان البريد الإلكتروني للشخص + الذي تريد دعوته - انقر على زر `Invite` لإرسال الدعوة + + + - يمكنك تكرار هذه العملية لدعوة أعضاء فريق متعددين - سيتلقى كل عضو + مدعو دعوة عبر البريد الإلكتروني للانضمام إلى مؤسستك + + + +## إضافة الأدوار + +يمكنك إضافة أدوار لأعضاء فريقك للتحكم في وصولهم إلى أجزاء مختلفة من المنصة. + + + + - سجّل الدخول إلى حساب CrewAI AMP - ابحث عن أيقونة الترس في + الزاوية العلوية اليمنى من لوحة التحكم - انقر على أيقونة الترس للوصول إلى + صفحة **Settings**: + + صفحة الإعدادات + + + + - في صفحة الإعدادات، سترى علامة تبويب `Roles` - انقر على علامة تبويب `Roles` + للوصول إلى صفحة **Roles**. + + علامة تبويب الأدوار + + - انقر على زر `Add Role` لإضافة دور جديد. - أدخل + تفاصيل وصلاحيات الدور وانقر على زر `Create Role` لإنشاء + الدور. + + نافذة إضافة الدور + + + + - في قسم الأعضاء، سترى قائمة بالأعضاء الحاليين (بما فيهم + أنت) + + العضو قبل الدعوة + + - بمجرد قبول العضو للدعوة، يمكنك إضافة دور + له. - عد إلى علامة تبويب `Roles` - انتقل إلى العضو الذي تريد إضافة + دور له وتحت عمود `Role`، انقر على القائمة المنسدلة - اختر الدور + الذي تريد إضافته للعضو - انقر على زر `Update` لحفظ الدور + + إضافة دور للعضو + + + + +## ملاحظات مهمة + +- **صلاحيات المسؤول**: فقط المستخدمون ذوو الصلاحيات الإدارية يمكنهم دعوة أعضاء جدد +- **دقة البريد الإلكتروني**: تأكد من صحة عناوين البريد الإلكتروني لأعضاء فريقك +- **قبول الدعوة**: سيحتاج الأعضاء المدعوون لقبول الدعوة للانضمام إلى مؤسستك +- **إشعارات البريد الإلكتروني**: قد ترغب في إعلام أعضاء فريقك بالتحقق من بريدهم الإلكتروني (بما في ذلك مجلدات البريد غير المرغوب) للدعوة + +باتباع هذه الخطوات، يمكنك بسهولة توسيع فريقك والتعاون بشكل أكثر فعالية داخل مؤسسة CrewAI AMP. diff --git a/docs/ar/enterprise/guides/tool-repository.mdx b/docs/ar/enterprise/guides/tool-repository.mdx new file mode 100644 index 000000000..9ff6b35b0 --- /dev/null +++ b/docs/ar/enterprise/guides/tool-repository.mdx @@ -0,0 +1,154 @@ +--- +title: مستودع الأدوات +description: "استخدام مستودع الأدوات لإدارة أدواتك" +icon: "toolbox" +mode: "wide" +--- + +## نظرة عامة + +مستودع الأدوات هو مدير حزم لأدوات CrewAI. يتيح للمستخدمين نشر وتثبيت وإدارة الأدوات التي تتكامل مع طواقم وتدفقات CrewAI. + +يمكن أن تكون الأدوات: + +- **خاصة**: متاحة فقط داخل مؤسستك (افتراضي) +- **عامة**: متاحة لجميع مستخدمي CrewAI إذا نُشرت بعلامة `--public` + +المستودع ليس نظام تحكم في الإصدارات. استخدم Git لتتبع تغييرات الكود وتمكين التعاون. + +## المتطلبات المسبقة + +قبل استخدام مستودع الأدوات، تأكد من أن لديك: + +- حساب [CrewAI AMP](https://app.crewai.com) +- [CrewAI CLI](/ar/concepts/cli#cli) مُثبّت +- uv>=0.5.0 مُثبّت. راجع [كيفية الترقية](https://docs.astral.sh/uv/getting-started/installation/#upgrading-uv) +- [Git](https://git-scm.com) مُثبّت ومُهيأ +- صلاحيات الوصول للنشر أو التثبيت في مؤسسة CrewAI AMP + +## تثبيت الأدوات + +لتثبيت أداة: + +```bash +crewai tool install +``` + +يثبّت هذا الأداة ويضيفها إلى `pyproject.toml`. + +يمكنك استخدام الأداة باستيرادها وإضافتها إلى وكلائك: + +```python +from your_tool.tool import YourTool + +custom_tool = YourTool() + +researcher = Agent( + role='Market Research Analyst', + goal='Provide up-to-date market analysis of the AI industry', + backstory='An expert analyst with a keen eye for market trends.', + tools=[custom_tool], + verbose=True +) +``` + +## إضافة حزم أخرى بعد تثبيت أداة + +بعد تثبيت أداة من مستودع أدوات CrewAI AMP، تحتاج لاستخدام أمر `crewai uv` لإضافة حزم أخرى لمشروعك. +استخدام أوامر `uv` المباشرة سيفشل لأن المصادقة لمستودع الأدوات يتم التعامل معها عبر CLI. باستخدام أمر `crewai uv`، يمكنك إضافة حزم أخرى لمشروعك دون القلق بشأن المصادقة. +يمكن استخدام أي أمر `uv` مع أمر `crewai uv`، مما يجعله أداة قوية لإدارة اعتماديات مشروعك دون عناء إدارة المصادقة عبر متغيرات البيئة أو طرق أخرى. + +لنفرض أنك ثبّت أداة مخصصة من مستودع أدوات CrewAI AMP تسمى "my-tool": + +```bash +crewai tool install my-tool +``` + +والآن تريد إضافة حزمة أخرى لمشروعك، يمكنك استخدام الأمر التالي: + +```bash +crewai uv add requests +``` + +أوامر أخرى مثل `uv sync` أو `uv remove` يمكن أيضاً استخدامها مع أمر `crewai uv`: + +```bash +crewai uv sync +``` + +```bash +crewai uv remove requests +``` + +سيضيف هذا الحزمة لمشروعك ويحدّث `pyproject.toml` وفقاً لذلك. + +## إنشاء ونشر الأدوات + +لإنشاء مشروع أداة جديد: + +```bash +crewai tool create +``` + +يولّد هذا مشروع أداة مُهيكل محلياً. + +بعد إجراء التغييرات، أنشئ مستودع Git وارفع الكود: + +```bash +git init +git add . +git commit -m "Initial version" +``` + +لنشر الأداة: + +```bash +crewai tool publish +``` + +افتراضياً، تُنشر الأدوات كخاصة. لجعل الأداة عامة: + +```bash +crewai tool publish --public +``` + +لمزيد من التفاصيل حول بناء الأدوات، راجع [إنشاء أدواتك الخاصة](/ar/concepts/tools#creating-your-own-tools). + +## تحديث الأدوات + +لتحديث أداة منشورة: + +1. عدّل الأداة محلياً +2. حدّث الإصدار في `pyproject.toml` (مثل من `0.1.0` إلى `0.1.1`) +3. ارفع التغييرات وانشر + +```bash +git commit -m "Update version to 0.1.1" +crewai tool publish +``` + +## حذف الأدوات + +لحذف أداة: + +1. انتقل إلى [CrewAI AMP](https://app.crewai.com) +2. انتقل إلى **Tools** +3. اختر الأداة +4. انقر على **Delete** + + + الحذف نهائي. لا يمكن استعادة أو إعادة تثبيت الأدوات المحذوفة. + + +## فحوصات الأمان + +كل إصدار منشور يخضع لفحوصات أمان آلية، ولا يكون متاحاً للتثبيت إلا بعد اجتيازها. + +يمكنك التحقق من حالة فحص الأمان للأداة في: + +`CrewAI AMP > Tools > Your Tool > Versions` + + + تواصل مع فريق الدعم للمساعدة في تكامل API أو + استكشاف الأخطاء. + diff --git a/docs/ar/enterprise/guides/training-crews.mdx b/docs/ar/enterprise/guides/training-crews.mdx new file mode 100644 index 000000000..77f9bb7bf --- /dev/null +++ b/docs/ar/enterprise/guides/training-crews.mdx @@ -0,0 +1,132 @@ +--- +title: "تدريب الطواقم" +description: "قم بتدريب طواقمك المنشورة مباشرة من منصة CrewAI AMP لتحسين أداء الوكلاء بمرور الوقت" +icon: "dumbbell" +mode: "wide" +--- + +يتيح لك التدريب تحسين أداء الطاقم من خلال تشغيل جلسات تدريب تكرارية مباشرة من علامة تبويب **Training** في CrewAI AMP. تستخدم المنصة **وضع التدريب التلقائي** — حيث تتولى العملية التكرارية تلقائياً، على عكس تدريب CLI الذي يتطلب ملاحظات بشرية تفاعلية لكل تكرار. + +بعد اكتمال التدريب، يقوم CrewAI بتقييم مخرجات الوكلاء ودمج الملاحظات في اقتراحات قابلة للتنفيذ لكل وكيل. يتم بعد ذلك تطبيق هذه الاقتراحات على تشغيلات الطاقم المستقبلية لتحسين جودة المخرجات. + + + للحصول على تفاصيل حول كيفية عمل تدريب CrewAI، راجع صفحة [مفاهيم التدريب](/ar/concepts/training). + + +## المتطلبات الأساسية + + + + تحتاج إلى حساب CrewAI AMP مع نشر نشط في حالة **Ready** (نوع Crew). + + + يجب أن يكون لحسابك صلاحية تشغيل للنشر الذي تريد تدريبه. + + + +## كيفية تدريب طاقم + + + + انتقل إلى **Deployments**، انقر على نشرك، ثم اختر علامة تبويب **Training**. + + + + قدم **Training Name** — سيصبح هذا اسم ملف `.pkl` المستخدم لتخزين نتائج التدريب. على سبيل المثال، "Expert Mode Training" ينتج `expert_mode_training.pkl`. + + + + أدخل حقول إدخال الطاقم. هذه هي نفس المدخلات التي ستقدمها للتشغيل العادي — يتم تحميلها ديناميكياً بناءً على تكوين طاقمك. + + + + انقر على **Train Crew**. يتغير الزر إلى "Training..." مع مؤشر دوران أثناء تشغيل العملية. + + خلف الكواليس: + - يتم إنشاء سجل تدريب للنشر الخاص بك + - تستدعي المنصة نقطة نهاية التدريب التلقائي للنشر + - يقوم الطاقم بتشغيل تكراراته تلقائياً — لا حاجة لملاحظات يدوية + + + + تعرض لوحة **Current Training Status**: + - **Status** — الحالة الحالية لجلسة التدريب + - **Nº Iterations** — عدد تكرارات التدريب المُهيأة + - **Filename** — ملف `.pkl` الذي يتم إنشاؤه + - **Started At** — وقت بدء التدريب + - **Training Inputs** — المدخلات التي قدمتها + + + +## فهم نتائج التدريب + +بمجرد اكتمال التدريب، سترى بطاقات نتائج لكل وكيل تحتوي على المعلومات التالية: + +- **Agent Role** — اسم/دور الوكيل في طاقمك +- **Final Quality** — درجة من 0 إلى 10 تقيّم جودة مخرجات الوكيل +- **Final Summary** — ملخص لأداء الوكيل أثناء التدريب +- **Suggestions** — توصيات قابلة للتنفيذ لتحسين سلوك الوكيل + +### تحرير الاقتراحات + +يمكنك تحسين الاقتراحات لأي وكيل: + + + + في بطاقة نتائج أي وكيل، انقر على زر **Edit** بجوار الاقتراحات. + + + + حدّث نص الاقتراحات ليعكس التحسينات التي تريدها بشكل أفضل. + + + + انقر على **Save**. تتم مزامنة الاقتراحات المُعدّلة مع النشر وتُستخدم في جميع التشغيلات المستقبلية. + + + +## استخدام بيانات التدريب + +لتطبيق نتائج التدريب على طاقمك: + +1. لاحظ **Training Filename** (ملف `.pkl`) من جلسة التدريب المكتملة. +2. حدد اسم الملف هذا في تكوين kickoff أو التشغيل الخاص بنشرك. +3. يقوم الطاقم تلقائياً بتحميل ملف التدريب وتطبيق الاقتراحات المخزنة على كل وكيل. + +هذا يعني أن الوكلاء يستفيدون من الملاحظات المُنشأة أثناء التدريب في كل تشغيل لاحق. + +## التدريبات السابقة + +يعرض الجزء السفلي من علامة تبويب Training **سجل جميع جلسات التدريب السابقة** للنشر. استخدم هذا لمراجعة التدريبات السابقة، ومقارنة النتائج، أو اختيار ملف تدريب مختلف للاستخدام. + +## معالجة الأخطاء + +إذا فشل تشغيل التدريب، تعرض لوحة الحالة حالة خطأ مع رسالة تصف ما حدث خطأ. + +الأسباب الشائعة لفشل التدريب: +- **لم يتم تحديث وقت تشغيل النشر** — تأكد من أن نشرك يعمل بأحدث إصدار +- **أخطاء تنفيذ الطاقم** — مشاكل في منطق مهام الطاقم أو تكوين الوكيل +- **مشاكل الشبكة** — مشاكل الاتصال بين المنصة والنشر + +## القيود + + + ضع هذه القيود في الاعتبار عند التخطيط لسير عمل التدريب الخاص بك: + - **تدريب نشط واحد في كل مرة** لكل نشر — انتظر حتى ينتهي التشغيل الحالي قبل بدء آخر + - **وضع التدريب التلقائي فقط** — لا تدعم المنصة الملاحظات التفاعلية لكل تكرار مثل CLI + - **بيانات التدريب خاصة بالنشر** — ترتبط نتائج التدريب بمثيل وإصدار النشر المحدد + + +## الموارد ذات الصلة + + + + تعلم كيف يعمل تدريب CrewAI. + + + قم بتشغيل طاقمك المنشور من منصة AMP. + + + انشر طاقمك واجعله جاهزاً للتدريب. + + diff --git a/docs/ar/enterprise/guides/update-crew.mdx b/docs/ar/enterprise/guides/update-crew.mdx new file mode 100644 index 000000000..1bb9ec82f --- /dev/null +++ b/docs/ar/enterprise/guides/update-crew.mdx @@ -0,0 +1,91 @@ +--- +title: "تحديث الطاقم" +description: "تحديث طاقم على CrewAI AMP" +icon: "pencil" +mode: "wide" +--- + + + بعد نشر طاقمك على CrewAI AMP، قد تحتاج لإجراء تحديثات على + الكود أو إعدادات الأمان أو التهيئة. يشرح هذا الدليل كيفية تنفيذ + عمليات التحديث الشائعة. + + +## لماذا تحديث طاقمك؟ + +لن يلتقط CrewAI تحديثات GitHub تلقائياً بشكل افتراضي، لذا ستحتاج لتشغيل التحديثات يدوياً، ما لم تكن قد حددت خيار `Auto-update` عند نشر طاقمك. + +هناك عدة أسباب قد تدفعك لتحديث نشر طاقمك: + +- تريد تحديث الكود بأحدث إيداع دفعته إلى GitHub +- تريد إعادة تعيين رمز الحامل لأسباب أمنية +- تريد تحديث متغيرات البيئة + +## 1. تحديث كود طاقمك لأحدث إيداع + +عندما تدفع إيداعات جديدة إلى مستودع GitHub وتريد تحديث نشرك: + +1. انتقل إلى طاقمك في منصة CrewAI AMP +2. انقر على زر `Re-deploy` في صفحة تفاصيل طاقمك + +![زر إعادة النشر](/images/enterprise/redeploy-button.png) + +سيؤدي ذلك إلى تشغيل تحديث يمكنك تتبعه عبر شريط التقدم. سيسحب النظام أحدث كود من مستودعك ويعيد بناء نشرك. + +## 2. إعادة تعيين رمز الحامل + +إذا كنت تحتاج لإنشاء رمز حامل جديد (مثلاً، إذا كنت تشتبه في أن الرمز الحالي ربما تم اختراقه): + +1. انتقل إلى طاقمك في منصة CrewAI AMP +2. ابحث عن قسم `Bearer Token` +3. انقر على زر `Reset` بجانب رمزك الحالي + +![إعادة تعيين الرمز](/images/enterprise/reset-token.png) + + + إعادة تعيين رمز الحامل ستبطل الرمز السابق فوراً. + تأكد من تحديث أي تطبيقات أو نصوص برمجية تستخدم الرمز القديم. + + +## 3. تحديث متغيرات البيئة + +لتحديث متغيرات البيئة لطاقمك: + +1. أولاً ادخل صفحة النشر بالنقر على اسم طاقمك + + + ![زر متغيرات البيئة](/images/enterprise/env-vars-button.png) + + +2. حدد موقع قسم `Environment Variables` (ستحتاج للنقر على أيقونة `Settings` للوصول إليه) +3. عدّل المتغيرات الحالية أو أضف جديدة في الحقول المتوفرة +4. انقر على زر `Update` بجانب كل متغير تعدّله + + + ![تحديث متغيرات البيئة](/images/enterprise/update-env-vars.png) + + +5. أخيراً، انقر على زر `Update Deployment` في أسفل الصفحة لتطبيق التغييرات + + + تحديث متغيرات البيئة سيشغّل نشراً جديداً، لكن هذا سيحدّث + فقط تهيئة البيئة وليس الكود نفسه. + + +## بعد التحديث + +بعد إجراء أي تحديث: + +1. سيعيد النظام بناء وإعادة نشر طاقمك +2. يمكنك مراقبة تقدم النشر في الوقت الفعلي +3. بمجرد الاكتمال، اختبر طاقمك للتأكد من أن التغييرات تعمل كما هو متوقع + + + إذا واجهت أي مشاكل بعد التحديث، يمكنك عرض سجلات النشر في + المنصة أو التواصل مع الدعم للمساعدة. + + + + تواصل مع فريق الدعم للمساعدة في تحديث طاقمك أو + استكشاف أخطاء النشر. + diff --git a/docs/ar/enterprise/guides/webhook-automation.mdx b/docs/ar/enterprise/guides/webhook-automation.mdx new file mode 100644 index 000000000..86d4ffe86 --- /dev/null +++ b/docs/ar/enterprise/guides/webhook-automation.mdx @@ -0,0 +1,157 @@ +--- +title: "أتمتة Webhook" +description: "أتمتة سير عمل CrewAI AMP باستخدام webhooks مع منصات مثل ActivePieces وZapier وMake.com" +icon: "webhook" +mode: "wide" +--- + +يتيح لك CrewAI AMP أتمتة سير عملك باستخدام webhooks. ستوجهك هذه المقالة خلال عملية إعداد واستخدام webhooks لبدء تنفيذ طاقمك، مع التركيز على التكامل مع ActivePieces، وهي منصة أتمتة سير العمل مشابهة لـ Zapier وMake.com. + +## إعداد Webhooks + + + + - انتقل إلى لوحة تحكم CrewAI AMP + - ابحث عن قسم `/kickoff`، الذي يُستخدم لبدء تنفيذ الطاقم + + واجهة البدء + + + + + في قسم محتوى JSON، ستحتاج إلى تقديم المعلومات التالية: + + - **inputs**: كائن JSON يحتوي على: + - `company`: اسم الشركة (مثال: "tesla") + - `product_name`: اسم المنتج (مثال: "crewai") + - `form_response`: نوع الاستجابة (مثال: "financial") + - `icp_description`: وصف موجز لملف العميل المثالي + - `product_description`: وصف قصير للمنتج + - `taskWebhookUrl`، `stepWebhookUrl`، `crewWebhookUrl`: عناوين URL لنقاط نهاية webhook المختلفة (ActivePieces أو Zapier أو Make.com أو منصة أخرى متوافقة) + + + + في هذا المثال سنستخدم ActivePieces. يمكنك استخدام منصات أخرى مثل Zapier وMake.com + + للتكامل مع ActivePieces: + + 1. أنشئ تدفقًا جديدًا في ActivePieces + 2. أضف مشغلًا (مثال: جدول `Every Day`) + + مشغل ActivePieces + + + 3. أضف خطوة إجراء HTTP + - عيّن الإجراء إلى `Send HTTP request` + - استخدم `POST` كطريقة + - عيّن عنوان URL إلى نقطة نهاية بدء CrewAI AMP + - أضف الترويسات اللازمة (مثال: `Bearer Token`) + + ترويسات ActivePieces + + + - في النص، ضمّن محتوى JSON كما تم تكوينه في الخطوة 2 + + نص ActivePieces + + + - سيبدأ الطاقم بعد ذلك في الوقت المحدد مسبقًا. + + + + 1. أنشئ تدفقًا جديدًا في ActivePieces وسمّه + + تدفق ActivePieces + + + 2. أضف خطوة webhook كمشغل: + - اختر `Catch Webhook` كنوع المشغل + - سيولّد هذا عنوان URL فريدًا سيستقبل طلبات HTTP ويشغل تدفقك + + Webhook ActivePieces + + + - كوّن البريد الإلكتروني لاستخدام نص جسم webhook الخاص بالطاقم + + بريد ActivePieces الإلكتروني + + + + + +## أمثلة مخرجات Webhook + +**ملاحظة:** أي كائن `meta` مُقدم في طلب البدء الخاص بك سيتم تضمينه في جميع حمولات webhook، مما يتيح لك تتبع الطلبات والحفاظ على السياق عبر دورة حياة تنفيذ الطاقم بالكامل. + + + + `stepWebhookUrl` - رد نداء يتم تنفيذه عند كل فكرة داخلية للوكيل + + ```json + { + "prompt": "Research the financial industry for potential AI solutions", + "thought": "I need to conduct preliminary research on the financial industry", + "tool": "research_tool", + "tool_input": "financial industry AI solutions", + "result": "**Preliminary Research Report on the Financial Industry for crewai Enterprise Solution**\n1. Industry Overview and Trends\nThe financial industry in ....\nConclusion:\nThe financial industry presents a fertile ground for implementing AI solutions like crewai, particularly in areas such as digital customer engagement, risk management, and regulatory compliance. Further engagement with the lead is recommended to better tailor the crewai solution to their specific needs and scale.", + "kickoff_id": "97eba64f-958c-40a0-b61c-625fe635a3c0", + "meta": { + "requestId": "travel-req-123", + "source": "web-app" + } + } + ``` + + + `taskWebhookUrl` - رد نداء يتم تنفيذه عند انتهاء كل مهمة + + ```json + { + "description": "Using the information gathered from the lead's data, conduct preliminary research on the lead's industry, company background, and potential use cases for crewai. Focus on finding relevant data that can aid in scoring the lead and planning a strategy to pitch them crewai.", + "name": "Industry Research Task", + "expected_output": "Detailed research report on the financial industry", + "summary": "The financial industry presents a fertile ground for implementing AI solutions like crewai, particularly in areas such as digital customer engagement, risk management, and regulatory compliance. Further engagement with the lead is recommended to better tailor the crewai solution to their specific needs and scale.", + "agent": "Research Agent", + "output": "**Preliminary Research Report on the Financial Industry for crewai Enterprise Solution**\n1. Industry Overview and Trends\nThe financial industry in ....\nConclusion:\nThe financial industry presents a fertile ground for implementing AI solutions like crewai, particularly in areas such as digital customer engagement, risk management, and regulatory compliance.", + "output_json": { + "industry": "financial", + "key_opportunities": ["digital customer engagement", "risk management", "regulatory compliance"] + }, + "kickoff_id": "97eba64f-958c-40a0-b61c-625fe635a3c0", + "meta": { + "requestId": "travel-req-123", + "source": "web-app" + } + } + ``` + + + `crewWebhookUrl` - رد نداء يتم تنفيذه عند انتهاء تنفيذ الطاقم + + ```json + { + "kickoff_id": "97eba64f-958c-40a0-b61c-625fe635a3c0", + "result": "**Final Analysis Report**\n\nLead Score: Customer service enhancement and compliance are particularly relevant.\n\nTalking Points:\n- Highlight how crewai's AI solutions can transform customer service\n- Discuss crewai's potential for sustainability goals\n- Emphasize compliance capabilities\n- Stress adaptability for various operation scales", + "result_json": { + "lead_score": "Customer service enhancement, and compliance are particularly relevant.", + "talking_points": [ + "Highlight how crewai's AI solutions can transform customer service with automated, personalized experiences and 24/7 support, improving both customer satisfaction and operational efficiency.", + "Discuss crewai's potential to help the institution achieve its sustainability goals through better data analysis and decision-making, contributing to responsible investing and green initiatives.", + "Emphasize crewai's ability to enhance compliance with evolving regulations through efficient data processing and reporting, reducing the risk of non-compliance penalties.", + "Stress the adaptability of crewai to support both extensive multinational operations and smaller, targeted projects, ensuring the solution grows with the institution's needs." + ] + }, + "token_usage": { + "total_tokens": 1250, + "prompt_tokens": 800, + "completion_tokens": 450 + }, + "meta": { + "requestId": "travel-req-123", + "source": "web-app" + } + } + ``` + + + diff --git a/docs/ar/enterprise/guides/zapier-trigger.mdx b/docs/ar/enterprise/guides/zapier-trigger.mdx new file mode 100644 index 000000000..ebeb1c863 --- /dev/null +++ b/docs/ar/enterprise/guides/zapier-trigger.mdx @@ -0,0 +1,105 @@ +--- +title: "مشغل Zapier" +description: "تشغيل أطقم CrewAI من سير عمل Zapier لأتمتة سير العمل عبر التطبيقات" +icon: "bolt" +mode: "wide" +--- + +سيرشدك هذا الدليل خلال عملية إعداد مشغلات Zapier لـ CrewAI AMP، مما يتيح لك أتمتة سير العمل بين CrewAI AMP والتطبيقات الأخرى. + +## المتطلبات الأساسية + +- حساب CrewAI AMP +- حساب Zapier +- حساب Slack (لهذا المثال المحدد) + +## الإعداد خطوة بخطوة + + + + - في Zapier، أنشئ Zap جديدًا. + + + Zapier 1 + + + + + + Zapier 2 + + - اختر `New Pushed Message` كحدث المشغل. + - اربط حساب Slack الخاص بك إذا لم تفعل ذلك بالفعل. + + + + - أضف خطوة إجراء جديدة إلى Zap الخاص بك. + - اختر CrewAI+ كتطبيق الإجراء وKickoff كحدث الإجراء + + + Zapier 5 + + + + + - اربط حساب CrewAI AMP الخاص بك. + - اختر الطاقم المناسب لسير عملك. + + + Zapier 6 + + - كوّن مدخلات الطاقم باستخدام البيانات من رسالة Slack. + + + + - أضف خطوة إجراء أخرى لتنسيق مخرجات النص من CrewAI AMP. + - استخدم أدوات التنسيق في Zapier لتحويل مخرجات Markdown إلى HTML. + + + Zapier 8 + + + Zapier 9 + + + + + - أضف خطوة إجراء نهائية لإرسال المخرجات المنسقة عبر البريد الإلكتروني. + - اختر خدمة البريد الإلكتروني المفضلة لديك (مثال: Gmail، Outlook). + - كوّن تفاصيل البريد الإلكتروني، بما في ذلك المستلم والموضوع والنص. + - أدرج مخرجات CrewAI AMP المنسقة في نص البريد الإلكتروني. + + + Zapier 7 + + + + + - أدخل النص في قناة Slack الخاصة بك + + + Zapier 10 + + + - اختر زر النقاط الثلاث ثم اختر Push to Zapier + + + Zapier 11 + + + + + + Zapier 12 + + + + + +## نصائح للنجاح + +- تأكد من أن مدخلات CrewAI AMP مربوطة بشكل صحيح من رسالة Slack. +- اختبر Zap الخاص بك جيدًا قبل تفعيله لاكتشاف أي مشاكل محتملة. +- فكر في إضافة خطوات معالجة الأخطاء لإدارة حالات الفشل المحتملة في سير العمل. + +باتباع هذه الخطوات، ستكون قد أعددت بنجاح مشغلات Zapier لـ CrewAI AMP، مما يتيح سير عمل آلي يتم تشغيله بواسطة رسائل Slack وينتج عنه إشعارات بالبريد الإلكتروني مع مخرجات CrewAI AMP. diff --git a/docs/ar/enterprise/integrations/asana.mdx b/docs/ar/enterprise/integrations/asana.mdx new file mode 100644 index 000000000..394d2193b --- /dev/null +++ b/docs/ar/enterprise/integrations/asana.mdx @@ -0,0 +1,271 @@ +--- +title: تكامل Asana +description: "تنسيق مهام الفريق والمشاريع مع تكامل Asana لـ CrewAI." +icon: "circle" +mode: "wide" +--- + +## نظرة عامة + +مكّن وكلاءك من إدارة المهام والمشاريع وتنسيق الفريق عبر Asana. أنشئ المهام وحدّث حالة المشروع وأدر التعيينات وبسّط سير عمل فريقك مع الأتمتة المدعومة بالذكاء الاصطناعي. + +## المتطلبات الأساسية + +قبل استخدام تكامل Asana، تأكد من أن لديك: + +- حساب [CrewAI AMP](https://app.crewai.com) مع اشتراك نشط +- حساب Asana مع الأذونات المناسبة +- ربط حساب Asana الخاص بك عبر [صفحة التكاملات](https://app.crewai.com/crewai_plus/connectors) + +## إعداد تكامل Asana + +### 1. ربط حساب Asana الخاص بك + +1. انتقل إلى [تكاملات CrewAI AMP](https://app.crewai.com/crewai_plus/connectors) +2. ابحث عن **Asana** في قسم تكاملات المصادقة +3. انقر على **ربط** وأكمل تدفق OAuth +4. امنح الأذونات اللازمة لإدارة المهام والمشاريع +5. انسخ رمز Enterprise الخاص بك من [إعدادات التكامل](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. تثبيت الحزمة المطلوبة + +```bash +uv add crewai-tools +``` + +### 3. إعداد متغير البيئة + + + لاستخدام التكاملات مع `Agent(apps=[])`, يجب تعيين متغير البيئة + `CREWAI_PLATFORM_INTEGRATION_TOKEN` برمز Enterprise الخاص بك. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +أو أضفه إلى ملف `.env`: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## الإجراءات المتاحة + + + + **الوصف:** إنشاء تعليق في Asana. + + **المعاملات:** + - `task` (string, مطلوب): معرف المهمة - معرف المهمة التي سيُضاف إليها التعليق. سيُنسب التعليق للمستخدم المصادق عليه حاليًا. + - `text` (string, مطلوب): النص (مثال: "This is a comment."). + + + + + **الوصف:** إنشاء مشروع في Asana. + + **المعاملات:** + - `name` (string, مطلوب): الاسم (مثال: "Stuff to buy"). + - `workspace` (string, مطلوب): مساحة العمل - استخدم إعدادات سير عمل بوابة الاتصال للسماح للمستخدمين باختيار مساحة العمل لإنشاء المشاريع فيها. الافتراضي هو أول مساحة عمل للمستخدم إذا تُرك فارغًا. + - `team` (string, اختياري): الفريق - استخدم إعدادات سير عمل بوابة الاتصال للسماح للمستخدمين باختيار الفريق لمشاركة هذا المشروع معه. الافتراضي هو أول فريق للمستخدم إذا تُرك فارغًا. + - `notes` (string, اختياري): ملاحظات (مثال: "These are things we need to purchase."). + + + + + **الوصف:** الحصول على قائمة المشاريع في Asana. + + **المعاملات:** + - `archived` (string, اختياري): مؤرشف - اختر "true" لعرض المشاريع المؤرشفة، "false" لعرض المشاريع النشطة فقط، أو "default" لعرض كليهما. + - الخيارات: `default`, `true`, `false` + + + + + **الوصف:** الحصول على مشروع بواسطة المعرف في Asana. + + **المعاملات:** + - `projectFilterId` (string, مطلوب): معرف المشروع. + + + + + **الوصف:** إنشاء مهمة في Asana. + + **المعاملات:** + - `name` (string, مطلوب): الاسم (مثال: "Task Name"). + - `workspace` (string, اختياري): مساحة العمل - استخدم إعدادات سير عمل بوابة الاتصال للسماح للمستخدمين باختيار مساحة العمل لإنشاء المهام فيها. الافتراضي هو أول مساحة عمل للمستخدم إذا تُرك فارغًا. + - `project` (string, اختياري): المشروع - استخدم إعدادات سير عمل بوابة الاتصال للسماح للمستخدمين باختيار المشروع لإنشاء هذه المهمة فيه. + - `notes` (string, اختياري): ملاحظات. + - `dueOnDate` (string, اختياري): تاريخ الاستحقاق - التاريخ الذي تستحق فيه هذه المهمة. لا يمكن استخدامه مع Due At. (مثال: "YYYY-MM-DD"). + - `dueAtDate` (string, اختياري): الاستحقاق في - التاريخ والوقت (طابع زمني ISO) الذي تستحق فيه هذه المهمة. لا يمكن استخدامه مع Due On. (مثال: "2019-09-15T02:06:58.147Z"). + - `assignee` (string, اختياري): المُكلف - معرف مستخدم Asana الذي سيتم تعيين هذه المهمة له. استخدم إعدادات سير عمل بوابة الاتصال للسماح للمستخدمين باختيار المُكلف. + - `gid` (string, اختياري): معرف خارجي - معرف من تطبيقك لربط هذه المهمة به. يمكنك استخدام هذا المعرف لمزامنة التحديثات لهذه المهمة لاحقًا. + + + + + **الوصف:** تحديث مهمة في Asana. + + **المعاملات:** + - `taskId` (string, مطلوب): معرف المهمة - معرف المهمة التي سيتم تحديثها. + - `completeStatus` (string, اختياري): حالة الإكمال. + - الخيارات: `true`, `false` + - `name` (string, اختياري): الاسم (مثال: "Task Name"). + - `notes` (string, اختياري): ملاحظات. + - `dueOnDate` (string, اختياري): تاريخ الاستحقاق - التاريخ الذي تستحق فيه هذه المهمة. لا يمكن استخدامه مع Due At. (مثال: "YYYY-MM-DD"). + - `dueAtDate` (string, اختياري): الاستحقاق في - التاريخ والوقت (طابع زمني ISO) الذي تستحق فيه هذه المهمة. لا يمكن استخدامه مع Due On. (مثال: "2019-09-15T02:06:58.147Z"). + - `assignee` (string, اختياري): المُكلف - معرف مستخدم Asana الذي سيتم تعيين هذه المهمة له. + - `gid` (string, اختياري): معرف خارجي - معرف من تطبيقك لربط هذه المهمة به. + + + + + **الوصف:** الحصول على قائمة المهام في Asana. + + **المعاملات:** + - `workspace` (string, اختياري): مساحة العمل - معرف مساحة العمل لتصفية المهام عليها. + - `project` (string, اختياري): المشروع - معرف المشروع لتصفية المهام عليه. + - `assignee` (string, اختياري): المُكلف - معرف المُكلف لتصفية المهام عليه. + - `completedSince` (string, اختياري): مكتملة منذ - إرجاع المهام غير المكتملة فقط أو التي اكتملت منذ هذا الوقت (طابع زمني ISO أو Unix). (مثال: "2014-04-25T16:15:47-04:00"). + + + + + **الوصف:** الحصول على قائمة المهام بواسطة المعرف في Asana. + + **المعاملات:** + - `taskId` (string, مطلوب): معرف المهمة. + + + + + **الوصف:** الحصول على مهمة بواسطة المعرف الخارجي في Asana. + + **المعاملات:** + - `gid` (string, مطلوب): المعرف الخارجي - المعرف الذي ترتبط أو تتزامن به هذه المهمة، من تطبيقك. + + + + + **الوصف:** إضافة مهمة إلى قسم في Asana. + + **المعاملات:** + - `sectionId` (string, مطلوب): معرف القسم - معرف القسم لإضافة هذه المهمة إليه. + - `taskId` (string, مطلوب): معرف المهمة - معرف المهمة. (مثال: "1204619611402340"). + - `beforeTaskId` (string, اختياري): معرف المهمة السابقة - معرف مهمة في هذا القسم سيتم إدراج هذه المهمة قبلها. لا يمكن استخدامه مع After Task ID. (مثال: "1204619611402340"). + - `afterTaskId` (string, اختياري): معرف المهمة التالية - معرف مهمة في هذا القسم سيتم إدراج هذه المهمة بعدها. لا يمكن استخدامه مع Before Task ID. (مثال: "1204619611402340"). + + + + + **الوصف:** الحصول على قائمة الفرق في Asana. + + **المعاملات:** + - `workspace` (string, مطلوب): مساحة العمل - إرجاع الفرق في مساحة العمل هذه المرئية للمستخدم المصرح له. + + + + + **الوصف:** الحصول على قائمة مساحات العمل في Asana. + + **المعاملات:** لا توجد معاملات مطلوبة. + + + + +## أمثلة الاستخدام + +### إعداد وكيل Asana الأساسي + +```python +from crewai import Agent, Task, Crew + +# Create an agent with Asana capabilities +asana_agent = Agent( + role="Project Manager", + goal="Manage tasks and projects in Asana efficiently", + backstory="An AI assistant specialized in project management and task coordination.", + apps=['asana'] # All Asana actions will be available +) + +# Task to create a new project +create_project_task = Task( + description="Create a new project called 'Q1 Marketing Campaign' in the Marketing workspace", + agent=asana_agent, + expected_output="Confirmation that the project was created successfully with project ID" +) + +# Run the task +crew = Crew( + agents=[asana_agent], + tasks=[create_project_task] +) + +crew.kickoff() +``` + +### تصفية أدوات Asana محددة + +```python +from crewai import Agent, Task, Crew + +# Create agent with specific Asana actions only +task_manager_agent = Agent( + role="Task Manager", + goal="Create and manage tasks efficiently", + backstory="An AI assistant that focuses on task creation and management.", + apps=[ + 'asana/create_task', + 'asana/update_task', + 'asana/get_tasks' + ] # Specific Asana actions +) + +# Task to create and assign a task +task_management = Task( + description="Create a task called 'Review quarterly reports' and assign it to the appropriate team member", + agent=task_manager_agent, + expected_output="Task created and assigned successfully" +) + +crew = Crew( + agents=[task_manager_agent], + tasks=[task_management] +) + +crew.kickoff() +``` + +### إدارة المشاريع المتقدمة + +```python +from crewai import Agent, Task, Crew + +project_coordinator = Agent( + role="Project Coordinator", + goal="Coordinate project activities and track progress", + backstory="An experienced project coordinator who ensures projects run smoothly.", + apps=['asana'] +) + +# Complex task involving multiple Asana operations +coordination_task = Task( + description=""" + 1. Get all active projects in the workspace + 2. For each project, get the list of incomplete tasks + 3. Create a summary report task in the 'Management Reports' project + 4. Add comments to overdue tasks to request status updates + """, + agent=project_coordinator, + expected_output="Summary report created and status update requests sent for overdue tasks" +) + +crew = Crew( + agents=[project_coordinator], + tasks=[coordination_task] +) + +crew.kickoff() +``` diff --git a/docs/ar/enterprise/integrations/box.mdx b/docs/ar/enterprise/integrations/box.mdx new file mode 100644 index 000000000..08186175f --- /dev/null +++ b/docs/ar/enterprise/integrations/box.mdx @@ -0,0 +1,280 @@ +--- +title: تكامل Box +description: "تخزين الملفات وإدارة المستندات مع تكامل Box لـ CrewAI." +icon: "box" +mode: "wide" +--- + +## نظرة عامة + +مكّن وكلاءك من إدارة الملفات والمجلدات والمستندات عبر Box. ارفع الملفات، ونظّم هياكل المجلدات، وابحث في المحتوى، وبسّط إدارة مستندات فريقك باستخدام الأتمتة المدعومة بالذكاء الاصطناعي. + +## المتطلبات الأساسية + +قبل استخدام تكامل Box، تأكد من توفر ما يلي: + +- حساب [CrewAI AMP](https://app.crewai.com) مع اشتراك فعّال +- حساب Box بالصلاحيات المناسبة +- ربط حساب Box الخاص بك عبر [صفحة التكاملات](https://app.crewai.com/crewai_plus/connectors) + +## إعداد تكامل Box + +### 1. ربط حساب Box الخاص بك + +1. انتقل إلى [تكاملات CrewAI AMP](https://app.crewai.com/crewai_plus/connectors) +2. ابحث عن **Box** في قسم تكاملات المصادقة +3. انقر على **Connect** وأكمل عملية OAuth +4. امنح الصلاحيات اللازمة لإدارة الملفات والمجلدات +5. انسخ رمز المؤسسة من [إعدادات التكامل](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. تثبيت الحزمة المطلوبة + +```bash +uv add crewai-tools +``` + +### 3. إعداد متغير البيئة + + + لاستخدام التكاملات مع `Agent(apps=[])`, يجب تعيين متغير البيئة + `CREWAI_PLATFORM_INTEGRATION_TOKEN` برمز المؤسسة الخاص بك. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +أو أضفه إلى ملف `.env`: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## الإجراءات المتاحة + + + + **الوصف:** حفظ ملف من عنوان URL في Box. + + **المعاملات:** + - `fileAttributes` (object, مطلوب): السمات - بيانات وصفية للملف تشمل الاسم والمجلد الأصلي والطوابع الزمنية. + ```json + { + "content_created_at": "2012-12-12T10:53:43-08:00", + "content_modified_at": "2012-12-12T10:53:43-08:00", + "name": "qwerty.png", + "parent": { "id": "1234567" } + } + ``` + - `file` (string, مطلوب): عنوان URL للملف - يجب أن يكون حجم الملفات أقل من 50 ميجابايت. (مثال: "https://picsum.photos/200/300"). + + + + + **الوصف:** حفظ ملف في Box. + + **المعاملات:** + - `file` (string, مطلوب): الملف - يقبل كائن ملف يحتوي على بيانات الملف. يجب أن يكون حجم الملفات أقل من 50 ميجابايت. + - `fileName` (string, مطلوب): اسم الملف (مثال: "qwerty.png"). + - `folder` (string, اختياري): المجلد - استخدم إعدادات سير عمل بوابة الاتصال للسماح للمستخدمين باختيار وجهة مجلد الملف. يستخدم المجلد الجذري افتراضياً إذا تُرك فارغاً. + + + + + **الوصف:** الحصول على ملف بواسطة المعرّف في Box. + + **المعاملات:** + - `fileId` (string, مطلوب): معرّف الملف - المعرّف الفريد الذي يمثل ملفاً. (مثال: "12345"). + + + + + **الوصف:** عرض قائمة الملفات في Box. + + **المعاملات:** + - `folderId` (string, مطلوب): معرّف المجلد - المعرّف الفريد الذي يمثل مجلداً. (مثال: "0"). + - `filterFormula` (object, اختياري): فلتر بصيغة التعبير العادي المنفصل - OR لمجموعات AND من شروط فردية. + ```json + { + "operator": "OR", + "conditions": [ + { + "operator": "AND", + "conditions": [ + { + "field": "direction", + "operator": "$stringExactlyMatches", + "value": "ASC" + } + ] + } + ] + } + ``` + + + + + **الوصف:** إنشاء مجلد في Box. + + **المعاملات:** + - `folderName` (string, مطلوب): الاسم - اسم المجلد الجديد. (مثال: "New Folder"). + - `folderParent` (object, مطلوب): المجلد الأصلي - المجلد الأصلي الذي سيُنشأ فيه المجلد الجديد. + ```json + { + "id": "123456" + } + ``` + + + + + **الوصف:** نقل مجلد في Box. + + **المعاملات:** + - `folderId` (string, مطلوب): معرّف المجلد - المعرّف الفريد الذي يمثل مجلداً. (مثال: "0"). + - `folderName` (string, مطلوب): الاسم - اسم المجلد. (مثال: "New Folder"). + - `folderParent` (object, مطلوب): المجلد الأصلي - وجهة المجلد الأصلي الجديد. + ```json + { + "id": "123456" + } + ``` + + + + + **الوصف:** الحصول على مجلد بواسطة المعرّف في Box. + + **المعاملات:** + - `folderId` (string, مطلوب): معرّف المجلد - المعرّف الفريد الذي يمثل مجلداً. (مثال: "0"). + + + + + **الوصف:** البحث في المجلدات في Box. + + **المعاملات:** + - `folderId` (string, مطلوب): معرّف المجلد - المجلد المراد البحث فيه. + - `filterFormula` (object, اختياري): فلتر بصيغة التعبير العادي المنفصل - OR لمجموعات AND من شروط فردية. + ```json + { + "operator": "OR", + "conditions": [ + { + "operator": "AND", + "conditions": [ + { + "field": "sort", + "operator": "$stringExactlyMatches", + "value": "name" + } + ] + } + ] + } + ``` + + + + + **الوصف:** حذف مجلد في Box. + + **المعاملات:** + - `folderId` (string, مطلوب): معرّف المجلد - المعرّف الفريد الذي يمثل مجلداً. (مثال: "0"). + - `recursive` (boolean, اختياري): تكراري - حذف مجلد غير فارغ بحذف المجلد وجميع محتوياته تكرارياً. + + + + +## أمثلة الاستخدام + +### إعداد Agent أساسي لـ Box + +```python +from crewai import Agent, Task, Crew +from crewai import Agent, Task, Crew + +# Create an agent with Box capabilities +box_agent = Agent( + role="Document Manager", + goal="Manage files and folders in Box efficiently", + backstory="An AI assistant specialized in document management and file organization.", + apps=['box'] # All Box actions will be available +) + +# Task to create a folder structure +create_structure_task = Task( + description="Create a folder called 'Project Files' in the root directory and upload a document from URL", + agent=box_agent, + expected_output="Folder created and file uploaded successfully" +) + +# Run the task +crew = Crew( + agents=[box_agent], + tasks=[create_structure_task] +) + +crew.kickoff() +``` + +### تصفية أدوات Box محددة + +```python +from crewai import Agent, Task, Crew + +# Create agent with specific Box actions only +file_organizer_agent = Agent( + role="File Organizer", + goal="Organize and manage file storage efficiently", + backstory="An AI assistant that focuses on file organization and storage management.", + apps=['box/create_folder', 'box/save_file', 'box/list_files'] # Specific Box actions +) + +# Task to organize files +organization_task = Task( + description="Create a folder structure for the marketing team and organize existing files", + agent=file_organizer_agent, + expected_output="Folder structure created and files organized" +) + +crew = Crew( + agents=[file_organizer_agent], + tasks=[organization_task] +) + +crew.kickoff() +``` + +### إدارة الملفات المتقدمة + +```python +from crewai import Agent, Task, Crew + +file_manager = Agent( + role="File Manager", + goal="Maintain organized file structure and manage document lifecycle", + backstory="An experienced file manager who ensures documents are properly organized and accessible.", + apps=['box'] +) + +# Complex task involving multiple Box operations +management_task = Task( + description=""" + 1. List all files in the root folder + 2. Create monthly archive folders for the current year + 3. Move old files to appropriate archive folders + 4. Generate a summary report of the file organization + """, + agent=file_manager, + expected_output="Files organized into archive structure with summary report" +) + +crew = Crew( + agents=[file_manager], + tasks=[management_task] +) + +crew.kickoff() +``` diff --git a/docs/ar/enterprise/integrations/clickup.mdx b/docs/ar/enterprise/integrations/clickup.mdx new file mode 100644 index 000000000..a8b75526c --- /dev/null +++ b/docs/ar/enterprise/integrations/clickup.mdx @@ -0,0 +1,301 @@ +--- +title: تكامل ClickUp +description: "إدارة المهام والإنتاجية مع تكامل ClickUp لـ CrewAI." +icon: "list-check" +mode: "wide" +--- + +## نظرة عامة + +مكّن وكلاءك من إدارة المهام والمشاريع وسير عمل الإنتاجية عبر ClickUp. أنشئ المهام وحدّثها، ونظّم المشاريع، وأدر تعيينات الفريق، وبسّط إدارة إنتاجيتك باستخدام الأتمتة المدعومة بالذكاء الاصطناعي. + +## المتطلبات الأساسية + +قبل استخدام تكامل ClickUp، تأكد من توفر ما يلي: + +- حساب [CrewAI AMP](https://app.crewai.com) مع اشتراك فعّال +- حساب ClickUp بالصلاحيات المناسبة +- ربط حساب ClickUp الخاص بك عبر [صفحة التكاملات](https://app.crewai.com/crewai_plus/connectors) + +## إعداد تكامل ClickUp + +### 1. ربط حساب ClickUp الخاص بك + +1. انتقل إلى [تكاملات CrewAI AMP](https://app.crewai.com/crewai_plus/connectors) +2. ابحث عن **ClickUp** في قسم تكاملات المصادقة +3. انقر على **Connect** وأكمل عملية OAuth +4. امنح الصلاحيات اللازمة لإدارة المهام والمشاريع +5. انسخ رمز المؤسسة من [إعدادات التكامل](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. تثبيت الحزمة المطلوبة + +```bash +uv add crewai-tools +``` + +### 3. إعداد متغير البيئة + + + لاستخدام التكاملات مع `Agent(apps=[])`, يجب تعيين متغير البيئة + `CREWAI_PLATFORM_INTEGRATION_TOKEN` برمز المؤسسة الخاص بك. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +أو أضفه إلى ملف `.env`: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## الإجراءات المتاحة + + + + **الوصف:** البحث عن المهام في ClickUp باستخدام فلاتر متقدمة. + + **المعاملات:** + - `taskFilterFormula` (object, اختياري): فلتر بصيغة التعبير العادي المنفصل - OR لمجموعات AND من شروط فردية. + ```json + { + "operator": "OR", + "conditions": [ + { + "operator": "AND", + "conditions": [ + { + "field": "statuses%5B%5D", + "operator": "$stringExactlyMatches", + "value": "open" + } + ] + } + ] + } + ``` + الحقول المتاحة: `space_ids%5B%5D`, `project_ids%5B%5D`, `list_ids%5B%5D`, `statuses%5B%5D`, `include_closed`, `assignees%5B%5D`, `tags%5B%5D`, `due_date_gt`, `due_date_lt`, `date_created_gt`, `date_created_lt`, `date_updated_gt`, `date_updated_lt` + + + + + **الوصف:** الحصول على المهام في قائمة محددة في ClickUp. + + **المعاملات:** + - `listId` (string, مطلوب): القائمة - اختر قائمة للحصول على المهام منها. استخدم إعدادات المستخدم في بوابة الاتصال للسماح للمستخدمين باختيار قائمة ClickUp. + - `taskFilterFormula` (string, اختياري): البحث عن المهام التي تطابق الفلاتر المحددة. مثال: name=task1. + + + + + **الوصف:** إنشاء مهمة في ClickUp. + + **المعاملات:** + - `listId` (string, مطلوب): القائمة - اختر قائمة لإنشاء هذه المهمة فيها. + - `name` (string, مطلوب): الاسم - اسم المهمة. + - `description` (string, اختياري): الوصف - وصف المهمة. + - `status` (string, اختياري): الحالة - اختر حالة لهذه المهمة. + - `assignees` (string, اختياري): المكلّفون - اختر عضواً (أو مصفوفة من معرّفات الأعضاء) ليتم تعيينهم لهذه المهمة. + - `dueDate` (string, اختياري): تاريخ الاستحقاق - حدد تاريخ استحقاق لهذه المهمة. + - `additionalFields` (string, اختياري): حقول إضافية - حدد حقولاً إضافية لتضمينها في هذه المهمة بصيغة JSON. + + + + + **الوصف:** تحديث مهمة في ClickUp. + + **المعاملات:** + - `taskId` (string, مطلوب): معرّف المهمة - معرّف المهمة المراد تحديثها. + - `listId` (string, مطلوب): القائمة - اختر قائمة لإنشاء هذه المهمة فيها. + - `name` (string, اختياري): الاسم - اسم المهمة. + - `description` (string, اختياري): الوصف - وصف المهمة. + - `status` (string, اختياري): الحالة - اختر حالة لهذه المهمة. + - `assignees` (string, اختياري): المكلّفون - اختر عضواً (أو مصفوفة من معرّفات الأعضاء) ليتم تعيينهم لهذه المهمة. + - `dueDate` (string, اختياري): تاريخ الاستحقاق - حدد تاريخ استحقاق لهذه المهمة. + - `additionalFields` (string, اختياري): حقول إضافية - حدد حقولاً إضافية لتضمينها في هذه المهمة بصيغة JSON. + + + + + **الوصف:** حذف مهمة في ClickUp. + + **المعاملات:** + - `taskId` (string, مطلوب): معرّف المهمة - معرّف المهمة المراد حذفها. + + + + + **الوصف:** الحصول على معلومات القائمة في ClickUp. + + **المعاملات:** + - `spaceId` (string, مطلوب): معرّف المساحة - معرّف المساحة التي تحتوي على القوائم. + + + + + **الوصف:** الحصول على الحقول المخصصة في قائمة في ClickUp. + + **المعاملات:** + - `listId` (string, مطلوب): معرّف القائمة - معرّف القائمة للحصول على الحقول المخصصة منها. + + + + + **الوصف:** الحصول على جميع الحقول في قائمة في ClickUp. + + **المعاملات:** + - `listId` (string, مطلوب): معرّف القائمة - معرّف القائمة للحصول على جميع الحقول منها. + + + + + **الوصف:** الحصول على معلومات المساحة في ClickUp. + + **المعاملات:** + - `spaceId` (string, اختياري): معرّف المساحة - معرّف المساحة المراد استرجاعها. + + + + + **الوصف:** الحصول على المجلدات في ClickUp. + + **المعاملات:** + - `spaceId` (string, مطلوب): معرّف المساحة - معرّف المساحة التي تحتوي على المجلدات. + + + + + **الوصف:** الحصول على معلومات العضو في ClickUp. + + **المعاملات:** لا توجد معاملات مطلوبة. + + + + +## أمثلة الاستخدام + +### إعداد Agent أساسي لـ ClickUp + +```python +from crewai import Agent, Task, Crew +from crewai import Agent, Task, Crew + +# Create an agent with Clickup capabilities +clickup_agent = Agent( + role="Task Manager", + goal="Manage tasks and projects in ClickUp efficiently", + backstory="An AI assistant specialized in task management and productivity coordination.", + apps=['clickup'] # All Clickup actions will be available +) + +# Task to create a new task +create_task = Task( + description="Create a task called 'Review Q1 Reports' in the Marketing list with high priority", + agent=clickup_agent, + expected_output="Task created successfully with task ID" +) + +# Run the task +crew = Crew( + agents=[clickup_agent], + tasks=[create_task] +) + +crew.kickoff() +``` + +### تصفية أدوات ClickUp محددة + +```python + +task_coordinator = Agent( + role="Task Coordinator", + goal="Create and manage tasks efficiently", + backstory="An AI assistant that focuses on task creation and status management.", + apps=['clickup/create_task'] +) + +# Task to manage task workflow +task_workflow = Task( + description="Create a task for project planning and assign it to the development team", + agent=task_coordinator, + expected_output="Task created and assigned successfully" +) + +crew = Crew( + agents=[task_coordinator], + tasks=[task_workflow] +) + +crew.kickoff() +``` + +### إدارة المشاريع المتقدمة + +```python +from crewai import Agent, Task, Crew + +project_manager = Agent( + role="Project Manager", + goal="Coordinate project activities and track team productivity", + backstory="An experienced project manager who ensures projects are delivered on time.", + apps=['clickup'] +) + +# Complex task involving multiple ClickUp operations +project_coordination = Task( + description=""" + 1. Get all open tasks in the current space + 2. Identify overdue tasks and update their status + 3. Create a weekly report task summarizing project progress + 4. Assign the report task to the team lead + """, + agent=project_manager, + expected_output="Project status updated and weekly report task created and assigned" +) + +crew = Crew( + agents=[project_manager], + tasks=[project_coordination] +) + +crew.kickoff() +``` + +### البحث في المهام وإدارتها + +```python +from crewai import Agent, Task, Crew + +task_analyst = Agent( + role="Task Analyst", + goal="Analyze task patterns and optimize team productivity", + backstory="An AI assistant that analyzes task data to improve team efficiency.", + apps=['clickup'] +) + +# Task to analyze and optimize task distribution +task_analysis = Task( + description=""" + Search for all tasks assigned to team members in the last 30 days, + analyze completion patterns, and create optimization recommendations + """, + agent=task_analyst, + expected_output="Task analysis report with optimization recommendations" +) + +crew = Crew( + agents=[task_analyst], + tasks=[task_analysis] +) + +crew.kickoff() +``` + +### الحصول على المساعدة + + + تواصل مع فريق الدعم للحصول على المساعدة في إعداد تكامل ClickUp أو + استكشاف الأخطاء وإصلاحها. + diff --git a/docs/ar/enterprise/integrations/github.mdx b/docs/ar/enterprise/integrations/github.mdx new file mode 100644 index 000000000..7737e6c3c --- /dev/null +++ b/docs/ar/enterprise/integrations/github.mdx @@ -0,0 +1,330 @@ +--- +title: تكامل GitHub +description: "إدارة المستودعات والمشكلات مع تكامل GitHub لـ CrewAI." +icon: "github" +mode: "wide" +--- + +## نظرة عامة + +مكّن وكلاءك من إدارة المستودعات والمشكلات والإصدارات عبر GitHub. أنشئ المشكلات وحدّثها، وأدر الإصدارات، وتتبع تطور المشاريع، وبسّط سير عمل تطوير البرمجيات باستخدام الأتمتة المدعومة بالذكاء الاصطناعي. + +## المتطلبات الأساسية + +قبل استخدام تكامل GitHub، تأكد من توفر ما يلي: + +- حساب [CrewAI AMP](https://app.crewai.com) مع اشتراك فعّال +- حساب GitHub بصلاحيات المستودع المناسبة +- ربط حساب GitHub الخاص بك عبر [صفحة التكاملات](https://app.crewai.com/crewai_plus/connectors) + +## إعداد تكامل GitHub + +### 1. ربط حساب GitHub الخاص بك + +1. انتقل إلى [تكاملات CrewAI AMP](https://app.crewai.com/crewai_plus/connectors) +2. ابحث عن **GitHub** في قسم تكاملات المصادقة +3. انقر على **Connect** وأكمل عملية OAuth +4. امنح الصلاحيات اللازمة لإدارة المستودعات والمشكلات +5. انسخ رمز المؤسسة من [إعدادات التكامل](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. تثبيت الحزمة المطلوبة + +```bash +uv add crewai-tools +``` + +### 3. إعداد متغير البيئة + + + لاستخدام التكاملات مع `Agent(apps=[])`, يجب تعيين متغير البيئة + `CREWAI_PLATFORM_INTEGRATION_TOKEN` برمز المؤسسة الخاص بك. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +أو أضفه إلى ملف `.env`: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## الإجراءات المتاحة + + + + **الوصف:** إنشاء مشكلة في GitHub. + + **المعاملات:** + - `owner` (string, مطلوب): المالك - حدد اسم مالك الحساب للمستودع المرتبط بهذه المشكلة. (مثال: "abc"). + - `repo` (string, مطلوب): المستودع - حدد اسم المستودع المرتبط بهذه المشكلة. + - `title` (string, مطلوب): عنوان المشكلة - حدد عنوان المشكلة المراد إنشاؤها. + - `body` (string, اختياري): محتوى المشكلة - حدد محتوى نص المشكلة المراد إنشاؤها. + - `assignees` (string, اختياري): المكلّفون - حدد اسم (أسماء) تسجيل الدخول في GitHub للمكلّفين كمصفوفة من السلاسل النصية لهذه المشكلة. (مثال: `["octocat"]`). + + + + + **الوصف:** تحديث مشكلة في GitHub. + + **المعاملات:** + - `owner` (string, مطلوب): المالك - حدد اسم مالك الحساب للمستودع المرتبط بهذه المشكلة. (مثال: "abc"). + - `repo` (string, مطلوب): المستودع - حدد اسم المستودع المرتبط بهذه المشكلة. + - `issue_number` (string, مطلوب): رقم المشكلة - حدد رقم المشكلة المراد تحديثها. + - `title` (string, مطلوب): عنوان المشكلة - حدد عنوان المشكلة المراد تحديثها. + - `body` (string, اختياري): محتوى المشكلة - حدد محتوى نص المشكلة المراد تحديثها. + - `assignees` (string, اختياري): المكلّفون - حدد اسم (أسماء) تسجيل الدخول في GitHub للمكلّفين كمصفوفة من السلاسل النصية لهذه المشكلة. (مثال: `["octocat"]`). + - `state` (string, اختياري): الحالة - حدد الحالة المحدّثة للمشكلة. + - الخيارات: `open`, `closed` + + + + + **الوصف:** الحصول على مشكلة بواسطة الرقم في GitHub. + + **المعاملات:** + - `owner` (string, مطلوب): المالك - حدد اسم مالك الحساب للمستودع المرتبط بهذه المشكلة. (مثال: "abc"). + - `repo` (string, مطلوب): المستودع - حدد اسم المستودع المرتبط بهذه المشكلة. + - `issue_number` (string, مطلوب): رقم المشكلة - حدد رقم المشكلة المراد جلبها. + + + + + **الوصف:** قفل مشكلة في GitHub. + + **المعاملات:** + - `owner` (string, مطلوب): المالك - حدد اسم مالك الحساب للمستودع المرتبط بهذه المشكلة. (مثال: "abc"). + - `repo` (string, مطلوب): المستودع - حدد اسم المستودع المرتبط بهذه المشكلة. + - `issue_number` (string, مطلوب): رقم المشكلة - حدد رقم المشكلة المراد قفلها. + - `lock_reason` (string, مطلوب): سبب القفل - حدد سبب قفل محادثة المشكلة أو طلب السحب. + - الخيارات: `off-topic`, `too heated`, `resolved`, `spam` + + + + + **الوصف:** البحث عن المشكلات في GitHub. + + **المعاملات:** + - `owner` (string, مطلوب): المالك - حدد اسم مالك الحساب للمستودع المرتبط بهذه المشكلة. (مثال: "abc"). + - `repo` (string, مطلوب): المستودع - حدد اسم المستودع المرتبط بهذه المشكلة. + - `filter` (object, مطلوب): فلتر بصيغة التعبير العادي المنفصل - OR لمجموعات AND من شروط فردية. + ```json + { + "operator": "OR", + "conditions": [ + { + "operator": "AND", + "conditions": [ + { + "field": "assignee", + "operator": "$stringExactlyMatches", + "value": "octocat" + } + ] + } + ] + } + ``` + الحقول المتاحة: `assignee`, `creator`, `mentioned`, `labels` + + + + + **الوصف:** إنشاء إصدار في GitHub. + + **المعاملات:** + - `owner` (string, مطلوب): المالك - حدد اسم مالك الحساب للمستودع المرتبط بهذا الإصدار. (مثال: "abc"). + - `repo` (string, مطلوب): المستودع - حدد اسم المستودع المرتبط بهذا الإصدار. + - `tag_name` (string, مطلوب): الاسم - حدد اسم وسم الإصدار المراد إنشاؤه. (مثال: "v1.0.0"). + - `target_commitish` (string, اختياري): الهدف - حدد هدف الإصدار. يمكن أن يكون اسم فرع أو SHA لعملية إيداع. الافتراضي هو الفرع الرئيسي. (مثال: "master"). + - `body` (string, اختياري): المحتوى - حدد وصفاً لهذا الإصدار. + - `draft` (string, اختياري): مسودة - حدد ما إذا كان الإصدار المُنشأ يجب أن يكون مسودة (غير منشور). + - الخيارات: `true`, `false` + - `prerelease` (string, اختياري): إصدار تجريبي - حدد ما إذا كان الإصدار المُنشأ يجب أن يكون إصداراً تجريبياً. + - الخيارات: `true`, `false` + - `discussion_category_name` (string, اختياري): اسم فئة المناقشة - إذا حُدد، يتم إنشاء مناقشة من الفئة المحددة وربطها بالإصدار. + - `generate_release_notes` (string, اختياري): ملاحظات الإصدار - حدد ما إذا كان يجب إنشاء ملاحظات الإصدار تلقائياً. + - الخيارات: `true`, `false` + + + + + **الوصف:** تحديث إصدار في GitHub. + + **المعاملات:** + - `owner` (string, مطلوب): المالك - حدد اسم مالك الحساب للمستودع المرتبط بهذا الإصدار. (مثال: "abc"). + - `repo` (string, مطلوب): المستودع - حدد اسم المستودع المرتبط بهذا الإصدار. + - `id` (string, مطلوب): معرّف الإصدار - حدد معرّف الإصدار المراد تحديثه. + - `tag_name` (string, اختياري): الاسم - حدد اسم وسم الإصدار المراد تحديثه. (مثال: "v1.0.0"). + - `target_commitish` (string, اختياري): الهدف - حدد هدف الإصدار. يمكن أن يكون اسم فرع أو SHA لعملية إيداع. الافتراضي هو الفرع الرئيسي. (مثال: "master"). + - `body` (string, اختياري): المحتوى - حدد وصفاً لهذا الإصدار. + - `draft` (string, اختياري): مسودة - حدد ما إذا كان الإصدار يجب أن يكون مسودة (غير منشور). + - الخيارات: `true`, `false` + - `prerelease` (string, اختياري): إصدار تجريبي - حدد ما إذا كان الإصدار يجب أن يكون إصداراً تجريبياً. + - الخيارات: `true`, `false` + - `discussion_category_name` (string, اختياري): اسم فئة المناقشة - إذا حُدد، يتم إنشاء مناقشة من الفئة المحددة وربطها بالإصدار. + - `generate_release_notes` (string, اختياري): ملاحظات الإصدار - حدد ما إذا كان يجب إنشاء ملاحظات الإصدار تلقائياً. + - الخيارات: `true`, `false` + + + + + **الوصف:** الحصول على إصدار بواسطة المعرّف في GitHub. + + **المعاملات:** + - `owner` (string, مطلوب): المالك - حدد اسم مالك الحساب للمستودع المرتبط بهذا الإصدار. (مثال: "abc"). + - `repo` (string, مطلوب): المستودع - حدد اسم المستودع المرتبط بهذا الإصدار. + - `id` (string, مطلوب): معرّف الإصدار - حدد معرّف الإصدار المراد جلبه. + + + + + **الوصف:** الحصول على إصدار بواسطة اسم الوسم في GitHub. + + **المعاملات:** + - `owner` (string, مطلوب): المالك - حدد اسم مالك الحساب للمستودع المرتبط بهذا الإصدار. (مثال: "abc"). + - `repo` (string, مطلوب): المستودع - حدد اسم المستودع المرتبط بهذا الإصدار. + - `tag_name` (string, مطلوب): الاسم - حدد وسم الإصدار المراد جلبه. (مثال: "v1.0.0"). + + + + + **الوصف:** حذف إصدار في GitHub. + + **المعاملات:** + - `owner` (string, مطلوب): المالك - حدد اسم مالك الحساب للمستودع المرتبط بهذا الإصدار. (مثال: "abc"). + - `repo` (string, مطلوب): المستودع - حدد اسم المستودع المرتبط بهذا الإصدار. + - `id` (string, مطلوب): معرّف الإصدار - حدد معرّف الإصدار المراد حذفه. + + + + +## أمثلة الاستخدام + +### إعداد Agent أساسي لـ GitHub + +```python +from crewai import Agent, Task, Crew +from crewai import Agent, Task, Crew + +# Create an agent with Github capabilities +github_agent = Agent( + role="Repository Manager", + goal="Manage GitHub repositories, issues, and releases efficiently", + backstory="An AI assistant specialized in repository management and issue tracking.", + apps=['github'] # All Github actions will be available +) + +# Task to create a new issue +create_issue_task = Task( + description="Create a bug report issue for the login functionality in the main repository", + agent=github_agent, + expected_output="Issue created successfully with issue number" +) + +# Run the task +crew = Crew( + agents=[github_agent], + tasks=[create_issue_task] +) + +crew.kickoff() +``` + +### تصفية أدوات GitHub محددة + +```python + +issue_manager = Agent( + role="Issue Manager", + goal="Create and manage GitHub issues efficiently", + backstory="An AI assistant that focuses on issue tracking and management.", + apps=['github/create_issue'] +) + +# Task to manage issue workflow +issue_workflow = Task( + description="Create a feature request issue and assign it to the development team", + agent=issue_manager, + expected_output="Feature request issue created and assigned successfully" +) + +crew = Crew( + agents=[issue_manager], + tasks=[issue_workflow] +) + +crew.kickoff() +``` + +### إدارة الإصدارات + +```python +from crewai import Agent, Task, Crew + +release_manager = Agent( + role="Release Manager", + goal="Manage software releases and versioning", + backstory="An experienced release manager who handles version control and release processes.", + apps=['github'] +) + +# Task to create a new release +release_task = Task( + description=""" + Create a new release v2.1.0 for the project with: + - Auto-generated release notes + - Target the main branch + - Include a description of new features and bug fixes + """, + agent=release_manager, + expected_output="Release v2.1.0 created successfully with release notes" +) + +crew = Crew( + agents=[release_manager], + tasks=[release_task] +) + +crew.kickoff() +``` + +### تتبع المشكلات وإدارتها + +```python +from crewai import Agent, Task, Crew + +project_coordinator = Agent( + role="Project Coordinator", + goal="Track and coordinate project issues and development progress", + backstory="An AI assistant that helps coordinate development work and track project progress.", + apps=['github'] +) + +# Complex task involving multiple GitHub operations +coordination_task = Task( + description=""" + 1. Search for all open issues assigned to the current milestone + 2. Identify overdue issues and update their priority labels + 3. Create a weekly progress report issue + 4. Lock resolved issues that have been inactive for 30 days + """, + agent=project_coordinator, + expected_output="Project coordination completed with progress report and issue management" +) + +crew = Crew( + agents=[project_coordinator], + tasks=[coordination_task] +) + +crew.kickoff() +``` + +### الحصول على المساعدة + + + تواصل مع فريق الدعم للحصول على المساعدة في إعداد تكامل GitHub أو + استكشاف الأخطاء وإصلاحها. + diff --git a/docs/ar/enterprise/integrations/gmail.mdx b/docs/ar/enterprise/integrations/gmail.mdx new file mode 100644 index 000000000..3b4db3fff --- /dev/null +++ b/docs/ar/enterprise/integrations/gmail.mdx @@ -0,0 +1,302 @@ +--- +title: تكامل Gmail +description: "إدارة البريد الإلكتروني وجهات الاتصال مع تكامل Gmail لـ CrewAI." +icon: "envelope" +mode: "wide" +--- + +## نظرة عامة + +مكّن وكلاءك من إدارة رسائل البريد الإلكتروني وجهات الاتصال والمسودات عبر Gmail. أرسل رسائل البريد الإلكتروني، وابحث في الرسائل، وأدر جهات الاتصال، وأنشئ المسودات، وبسّط اتصالات البريد الإلكتروني باستخدام الأتمتة المدعومة بالذكاء الاصطناعي. + +## المتطلبات الأساسية + +قبل استخدام تكامل Gmail، تأكد من توفر ما يلي: + +- حساب [CrewAI AMP](https://app.crewai.com) مع اشتراك فعّال +- حساب Gmail بالصلاحيات المناسبة +- ربط حساب Gmail الخاص بك عبر [صفحة التكاملات](https://app.crewai.com/crewai_plus/connectors) + +## إعداد تكامل Gmail + +### 1. ربط حساب Gmail الخاص بك + +1. انتقل إلى [تكاملات CrewAI AMP](https://app.crewai.com/crewai_plus/connectors) +2. ابحث عن **Gmail** في قسم تكاملات المصادقة +3. انقر على **Connect** وأكمل عملية OAuth +4. امنح الصلاحيات اللازمة لإدارة البريد الإلكتروني وجهات الاتصال +5. انسخ رمز المؤسسة من [إعدادات التكامل](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. تثبيت الحزمة المطلوبة + +```bash +uv add crewai-tools +``` + +### 3. إعداد متغير البيئة + + + لاستخدام التكاملات مع `Agent(apps=[])`, يجب تعيين متغير البيئة + `CREWAI_PLATFORM_INTEGRATION_TOKEN` برمز المؤسسة الخاص بك. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +أو أضفه إلى ملف `.env`: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## الإجراءات المتاحة + + + + **الوصف:** استرجاع قائمة بالرسائل. + + **المعاملات:** + - `userId` (string, مطلوب): عنوان البريد الإلكتروني للمستخدم أو 'me' للمستخدم المصادق عليه. (الافتراضي: "me") + - `q` (string, اختياري): استعلام بحث لتصفية الرسائل (مثال: 'from:someone@example.com is:unread'). + - `maxResults` (integer, اختياري): الحد الأقصى لعدد الرسائل المُرجعة (1-500). (الافتراضي: 100) + - `pageToken` (string, اختياري): رمز الصفحة لاسترجاع صفحة محددة من النتائج. + - `labelIds` (array, اختياري): إرجاع الرسائل ذات التصنيفات التي تطابق جميع معرّفات التصنيف المحددة فقط. + - `includeSpamTrash` (boolean, اختياري): تضمين رسائل البريد العشوائي والمحذوفات في النتائج. (الافتراضي: false) + + + + + **الوصف:** إرسال بريد إلكتروني. + + **المعاملات:** + - `to` (string, مطلوب): عنوان البريد الإلكتروني للمستلم. + - `subject` (string, مطلوب): سطر موضوع البريد الإلكتروني. + - `body` (string, مطلوب): محتوى رسالة البريد الإلكتروني. + - `userId` (string, اختياري): عنوان البريد الإلكتروني للمستخدم أو 'me' للمستخدم المصادق عليه. (الافتراضي: "me") + - `cc` (string, اختياري): عناوين نسخة كربونية (مفصولة بفواصل). + - `bcc` (string, اختياري): عناوين نسخة كربونية مخفية (مفصولة بفواصل). + - `from` (string, اختياري): عنوان المرسل (إذا كان مختلفاً عن المستخدم المصادق عليه). + - `replyTo` (string, اختياري): عنوان الرد. + - `threadId` (string, اختياري): معرّف السلسلة إذا كان الرد على محادثة موجودة. + + + + + **الوصف:** حذف بريد إلكتروني بواسطة المعرّف. + + **المعاملات:** + - `userId` (string, مطلوب): عنوان البريد الإلكتروني للمستخدم أو 'me' للمستخدم المصادق عليه. + - `id` (string, مطلوب): معرّف الرسالة المراد حذفها. + + + + + **الوصف:** إنشاء مسودة بريد إلكتروني جديدة. + + **المعاملات:** + - `userId` (string, مطلوب): عنوان البريد الإلكتروني للمستخدم أو 'me' للمستخدم المصادق عليه. + - `message` (object, مطلوب): كائن الرسالة الذي يحتوي على محتوى المسودة. + - `raw` (string, مطلوب): رسالة البريد الإلكتروني بترميز base64url. + + + + + **الوصف:** استرجاع رسالة محددة بواسطة المعرّف. + + **المعاملات:** + - `userId` (string, مطلوب): عنوان البريد الإلكتروني للمستخدم أو 'me' للمستخدم المصادق عليه. (الافتراضي: "me") + - `id` (string, مطلوب): معرّف الرسالة المراد استرجاعها. + - `format` (string, اختياري): صيغة إرجاع الرسالة. الخيارات: "full", "metadata", "minimal", "raw". (الافتراضي: "full") + - `metadataHeaders` (array, اختياري): عند التحديد وكانت الصيغة METADATA، يتم تضمين الترويسات المحددة فقط. + + + + + **الوصف:** استرجاع مرفق رسالة. + + **المعاملات:** + - `userId` (string, مطلوب): عنوان البريد الإلكتروني للمستخدم أو 'me' للمستخدم المصادق عليه. (الافتراضي: "me") + - `messageId` (string, مطلوب): معرّف الرسالة التي تحتوي على المرفق. + - `id` (string, مطلوب): معرّف المرفق المراد استرجاعه. + + + + + **الوصف:** استرجاع سلسلة بريد إلكتروني محددة بواسطة المعرّف. + + **المعاملات:** + - `userId` (string, مطلوب): عنوان البريد الإلكتروني للمستخدم أو 'me' للمستخدم المصادق عليه. (الافتراضي: "me") + - `id` (string, مطلوب): معرّف السلسلة المراد استرجاعها. + - `format` (string, اختياري): صيغة إرجاع الرسائل. الخيارات: "full", "metadata", "minimal". (الافتراضي: "full") + - `metadataHeaders` (array, اختياري): عند التحديد وكانت الصيغة METADATA، يتم تضمين الترويسات المحددة فقط. + + + + + **الوصف:** تعديل التصنيفات المُطبقة على سلسلة. + + **المعاملات:** + - `userId` (string, مطلوب): عنوان البريد الإلكتروني للمستخدم أو 'me' للمستخدم المصادق عليه. (الافتراضي: "me") + - `id` (string, مطلوب): معرّف السلسلة المراد تعديلها. + - `addLabelIds` (array, اختياري): قائمة بمعرّفات التصنيفات المراد إضافتها لهذه السلسلة. + - `removeLabelIds` (array, اختياري): قائمة بمعرّفات التصنيفات المراد إزالتها من هذه السلسلة. + + + + + **الوصف:** نقل سلسلة إلى سلة المحذوفات. + + **المعاملات:** + - `userId` (string, مطلوب): عنوان البريد الإلكتروني للمستخدم أو 'me' للمستخدم المصادق عليه. (الافتراضي: "me") + - `id` (string, مطلوب): معرّف السلسلة المراد حذفها. + + + + + **الوصف:** إزالة سلسلة من سلة المحذوفات. + + **المعاملات:** + - `userId` (string, مطلوب): عنوان البريد الإلكتروني للمستخدم أو 'me' للمستخدم المصادق عليه. (الافتراضي: "me") + - `id` (string, مطلوب): معرّف السلسلة المراد استعادتها. + + + + +## أمثلة الاستخدام + +### إعداد Agent أساسي لـ Gmail + +```python +from crewai import Agent, Task, Crew + +# Create an agent with Gmail capabilities +gmail_agent = Agent( + role="Email Manager", + goal="Manage email communications and messages efficiently", + backstory="An AI assistant specialized in email management and communication.", + apps=['gmail'] # All Gmail actions will be available +) + +# Task to send a follow-up email +send_email_task = Task( + description="Send a follow-up email to john@example.com about the project update meeting", + agent=gmail_agent, + expected_output="Email sent successfully with confirmation" +) + +# Run the task +crew = Crew( + agents=[gmail_agent], + tasks=[send_email_task] +) + +crew.kickoff() +``` + +### تصفية أدوات Gmail محددة + +```python +from crewai import Agent, Task, Crew + +# Create agent with specific Gmail actions only +email_coordinator = Agent( + role="Email Coordinator", + goal="Coordinate email communications and manage drafts", + backstory="An AI assistant that focuses on email coordination and draft management.", + apps=[ + 'gmail/send_email', + 'gmail/fetch_emails', + 'gmail/create_draft' + ] +) + +# Task to prepare and send emails +email_coordination = Task( + description="Search for emails from the marketing team, create a summary draft, and send it to stakeholders", + agent=email_coordinator, + expected_output="Summary email sent to stakeholders" +) + +crew = Crew( + agents=[email_coordinator], + tasks=[email_coordination] +) + +crew.kickoff() +``` + +### البحث في البريد الإلكتروني وتحليله + +```python +from crewai import Agent, Task, Crew + +# Create agent with Gmail search and analysis capabilities +email_analyst = Agent( + role="Email Analyst", + goal="Analyze email patterns and provide insights", + backstory="An AI assistant that analyzes email data to provide actionable insights.", + apps=['gmail/fetch_emails', 'gmail/get_message'] # Specific actions for email analysis +) + +# Task to analyze email patterns +analysis_task = Task( + description=""" + Search for all unread emails from the last 7 days, + categorize them by sender domain, + and create a summary report of communication patterns + """, + agent=email_analyst, + expected_output="Email analysis report with communication patterns and recommendations" +) + +crew = Crew( + agents=[email_analyst], + tasks=[analysis_task] +) + +crew.kickoff() +``` + +### إدارة السلاسل + +```python +from crewai import Agent, Task, Crew + +# Create agent with Gmail thread management capabilities +thread_manager = Agent( + role="Thread Manager", + goal="Organize and manage email threads efficiently", + backstory="An AI assistant that specializes in email thread organization and management.", + apps=[ + 'gmail/fetch_thread', + 'gmail/modify_thread', + 'gmail/trash_thread' + ] +) + +# Task to organize email threads +thread_task = Task( + description=""" + 1. Fetch all threads from the last month + 2. Apply appropriate labels to organize threads by project + 3. Archive or trash threads that are no longer relevant + """, + agent=thread_manager, + expected_output="Email threads organized with appropriate labels and cleanup completed" +) + +crew = Crew( + agents=[thread_manager], + tasks=[thread_task] +) + +crew.kickoff() +``` + +### الحصول على المساعدة + + + تواصل مع فريق الدعم للحصول على المساعدة في إعداد تكامل Gmail أو + استكشاف الأخطاء وإصلاحها. + diff --git a/docs/ar/enterprise/integrations/google_calendar.mdx b/docs/ar/enterprise/integrations/google_calendar.mdx new file mode 100644 index 000000000..f82b6cb18 --- /dev/null +++ b/docs/ar/enterprise/integrations/google_calendar.mdx @@ -0,0 +1,366 @@ +--- +title: تكامل Google Calendar +description: "إدارة الأحداث والجداول الزمنية مع تكامل Google Calendar لـ CrewAI." +icon: "calendar" +mode: "wide" +--- + +## نظرة عامة + +مكّن وكلاءك من إدارة أحداث التقويم والجداول الزمنية والتوفر عبر Google Calendar. أنشئ الأحداث وحدّثها، وأدر الحضور، وتحقق من التوفر، وبسّط سير عمل الجدولة باستخدام الأتمتة المدعومة بالذكاء الاصطناعي. + +## المتطلبات الأساسية + +قبل استخدام تكامل Google Calendar، تأكد من توفر ما يلي: + +- حساب [CrewAI AMP](https://app.crewai.com) مع اشتراك فعّال +- حساب Google مع إمكانية الوصول إلى Google Calendar +- ربط حساب Google الخاص بك عبر [صفحة التكاملات](https://app.crewai.com/crewai_plus/connectors) + +## إعداد تكامل Google Calendar + +### 1. ربط حساب Google الخاص بك + +1. انتقل إلى [تكاملات CrewAI AMP](https://app.crewai.com/crewai_plus/connectors) +2. ابحث عن **Google Calendar** في قسم تكاملات المصادقة +3. انقر على **Connect** وأكمل عملية OAuth +4. امنح الصلاحيات اللازمة للوصول إلى التقويم +5. انسخ رمز المؤسسة من [إعدادات التكامل](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. تثبيت الحزمة المطلوبة + +```bash +uv add crewai-tools +``` + +### 3. إعداد متغير البيئة + + + لاستخدام التكاملات مع `Agent(apps=[])`, يجب تعيين متغير البيئة + `CREWAI_PLATFORM_INTEGRATION_TOKEN` برمز المؤسسة الخاص بك. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +أو أضفه إلى ملف `.env`: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## الإجراءات المتاحة + + + + **الوصف:** الحصول على توفر التقويم (معلومات مشغول/متاح). + + **المعاملات:** + - `timeMin` (string, مطلوب): وقت البداية (بصيغة RFC3339) + - `timeMax` (string, مطلوب): وقت النهاية (بصيغة RFC3339) + - `items` (array, مطلوب): معرّفات التقاويم المراد التحقق منها + ```json + [ + { + "id": "calendar_id" + } + ] + ``` + - `timeZone` (string, اختياري): المنطقة الزمنية المستخدمة في الاستجابة. الافتراضي هو UTC. + - `groupExpansionMax` (integer, اختياري): الحد الأقصى لعدد معرّفات التقاويم لمجموعة واحدة. الحد الأقصى: 100 + - `calendarExpansionMax` (integer, اختياري): الحد الأقصى لعدد التقاويم لتقديم معلومات التوفر. الحد الأقصى: 50 + + + + + **الوصف:** إنشاء حدث جديد في التقويم المحدد. + + **المعاملات:** + - `calendarId` (string, مطلوب): معرّف التقويم (استخدم 'primary' للتقويم الرئيسي) + - `summary` (string, مطلوب): عنوان/ملخص الحدث + - `start_dateTime` (string, مطلوب): وقت البداية بصيغة RFC3339 (مثال: 2024-01-20T10:00:00-07:00) + - `end_dateTime` (string, مطلوب): وقت النهاية بصيغة RFC3339 + - `description` (string, اختياري): وصف الحدث + - `timeZone` (string, اختياري): المنطقة الزمنية (مثال: America/Los_Angeles) + - `location` (string, اختياري): الموقع الجغرافي للحدث كنص حر. + - `attendees` (array, اختياري): قائمة الحضور للحدث. + ```json + [ + { + "email": "attendee@example.com", + "displayName": "Attendee Name", + "optional": false + } + ] + ``` + - `reminders` (object, اختياري): معلومات حول تذكيرات الحدث. + ```json + { + "useDefault": true, + "overrides": [ + { + "method": "email", + "minutes": 15 + } + ] + } + ``` + - `conferenceData` (object, اختياري): المعلومات المتعلقة بالمؤتمر، مثل تفاصيل مؤتمر Google Meet. + ```json + { + "createRequest": { + "requestId": "unique-request-id", + "conferenceSolutionKey": { + "type": "hangoutsMeet" + } + } + } + ``` + - `visibility` (string, اختياري): ظهور الحدث. الخيارات: default, public, private, confidential. الافتراضي: default + - `transparency` (string, اختياري): ما إذا كان الحدث يحجب الوقت في التقويم. الخيارات: opaque, transparent. الافتراضي: opaque + + + + + **الوصف:** استرجاع الأحداث للتقويم المحدد. + + **المعاملات:** + - `calendarId` (string, مطلوب): معرّف التقويم (استخدم 'primary' للتقويم الرئيسي) + - `timeMin` (string, اختياري): الحد الأدنى للأحداث (بصيغة RFC3339) + - `timeMax` (string, اختياري): الحد الأعلى للأحداث (بصيغة RFC3339) + - `maxResults` (integer, اختياري): الحد الأقصى لعدد الأحداث (الافتراضي 10). الحد الأدنى: 1، الحد الأقصى: 2500 + - `orderBy` (string, اختياري): ترتيب الأحداث في النتيجة. الخيارات: startTime, updated. الافتراضي: startTime + - `singleEvents` (boolean, اختياري): ما إذا كان يجب توسيع الأحداث المتكررة إلى نُسخ فردية. الافتراضي: true + - `showDeleted` (boolean, اختياري): ما إذا كان يجب تضمين الأحداث المحذوفة. الافتراضي: false + - `showHiddenInvitations` (boolean, اختياري): ما إذا كان يجب تضمين الدعوات المخفية. الافتراضي: false + - `q` (string, اختياري): مصطلحات بحث نصية حرة للعثور على الأحداث المطابقة في أي حقل. + - `pageToken` (string, اختياري): رمز يحدد صفحة النتائج المراد إرجاعها. + - `timeZone` (string, اختياري): المنطقة الزمنية المستخدمة في الاستجابة. + - `updatedMin` (string, اختياري): الحد الأدنى لوقت آخر تعديل للحدث (بصيغة RFC3339) للتصفية. + - `iCalUID` (string, اختياري): يحدد معرّف حدث بصيغة iCalendar ليتم تقديمه في الاستجابة. + + + + + **الوصف:** تحديث حدث موجود. + + **المعاملات:** + - `calendarId` (string, مطلوب): معرّف التقويم + - `eventId` (string, مطلوب): معرّف الحدث المراد تحديثه + - `summary` (string, اختياري): عنوان الحدث المحدّث + - `description` (string, اختياري): وصف الحدث المحدّث + - `start_dateTime` (string, اختياري): وقت البداية المحدّث + - `end_dateTime` (string, اختياري): وقت النهاية المحدّث + + + + + **الوصف:** حذف حدث محدد. + + **المعاملات:** + - `calendarId` (string, مطلوب): معرّف التقويم + - `eventId` (string, مطلوب): معرّف الحدث المراد حذفه + + + + + **الوصف:** استرجاع قائمة تقاويم المستخدم. + + **المعاملات:** + - `maxResults` (integer, اختياري): الحد الأقصى لعدد الإدخالات في صفحة نتائج واحدة. الحد الأدنى: 1 + - `pageToken` (string, اختياري): رمز يحدد صفحة النتائج المراد إرجاعها. + - `showDeleted` (boolean, اختياري): ما إذا كان يجب تضمين إدخالات قائمة التقويم المحذوفة. الافتراضي: false + - `showHidden` (boolean, اختياري): ما إذا كان يجب عرض الإدخالات المخفية. الافتراضي: false + - `minAccessRole` (string, اختياري): الحد الأدنى لدور الوصول للمستخدم. الخيارات: freeBusyReader, owner, reader, writer + + + + +## أمثلة الاستخدام + +### إعداد Agent أساسي للتقويم + +```python +from crewai import Agent, Task, Crew + +# Create an agent with Google Calendar capabilities +calendar_agent = Agent( + role="Schedule Manager", + goal="Manage calendar events and scheduling efficiently", + backstory="An AI assistant specialized in calendar management and scheduling coordination.", + apps=['google_calendar'] # All Google Calendar actions will be available +) + +# Task to create a meeting +create_meeting_task = Task( + description="Create a team standup meeting for tomorrow at 9 AM with the development team", + agent=calendar_agent, + expected_output="Meeting created successfully with Google Meet link" +) + +# Run the task +crew = Crew( + agents=[calendar_agent], + tasks=[create_meeting_task] +) + +crew.kickoff() +``` + +### تصفية أدوات التقويم المحددة + +```python +meeting_coordinator = Agent( + role="Meeting Coordinator", + goal="Coordinate meetings and check availability", + backstory="An AI assistant that focuses on meeting scheduling and availability management.", + apps=['google_calendar/create_event', 'google_calendar/get_availability'] +) + +# Task to schedule a meeting with availability check +schedule_meeting = Task( + description="Check availability for next week and schedule a project review meeting with stakeholders", + agent=meeting_coordinator, + expected_output="Meeting scheduled after checking availability of all participants" +) + +crew = Crew( + agents=[meeting_coordinator], + tasks=[schedule_meeting] +) + +crew.kickoff() +``` + +### إدارة الأحداث وتحديثاتها + +```python +from crewai import Agent, Task, Crew + +event_manager = Agent( + role="Event Manager", + goal="Manage and update calendar events efficiently", + backstory="An experienced event manager who handles event logistics and updates.", + apps=['google_calendar'] +) + +# Task to manage event updates +event_management = Task( + description=""" + 1. List all events for this week + 2. Update any events that need location changes to include video conference links + 3. Check availability for upcoming meetings + """, + agent=event_manager, + expected_output="Weekly events updated with proper locations and availability checked" +) + +crew = Crew( + agents=[event_manager], + tasks=[event_management] +) + +crew.kickoff() +``` + +### التوفر وإدارة التقويم + +```python +from crewai import Agent, Task, Crew + +availability_coordinator = Agent( + role="Availability Coordinator", + goal="Coordinate availability and manage calendars for scheduling", + backstory="An AI assistant that specializes in availability management and calendar coordination.", + apps=['google_calendar'] +) + +# Task to coordinate availability +availability_task = Task( + description=""" + 1. Get the list of available calendars + 2. Check availability for all calendars next Friday afternoon + 3. Create a team meeting for the first available 2-hour slot + 4. Include Google Meet link and send invitations + """, + agent=availability_coordinator, + expected_output="Team meeting scheduled based on availability with all team members invited" +) + +crew = Crew( + agents=[availability_coordinator], + tasks=[availability_task] +) + +crew.kickoff() +``` + +### سير عمل الجدولة الآلية + +```python +from crewai import Agent, Task, Crew + +scheduling_automator = Agent( + role="Scheduling Automator", + goal="Automate scheduling workflows and calendar management", + backstory="An AI assistant that automates complex scheduling scenarios and calendar workflows.", + apps=['google_calendar'] +) + +# Complex scheduling automation task +automation_task = Task( + description=""" + 1. List all upcoming events for the next two weeks + 2. Identify any scheduling conflicts or back-to-back meetings + 3. Suggest optimal meeting times by checking availability + 4. Create buffer time between meetings where needed + 5. Update event descriptions with agenda items and meeting links + """, + agent=scheduling_automator, + expected_output="Calendar optimized with resolved conflicts, buffer times, and updated meeting details" +) + +crew = Crew( + agents=[scheduling_automator], + tasks=[automation_task] +) + +crew.kickoff() +``` + +## استكشاف الأخطاء وإصلاحها + +### المشاكل الشائعة + +**أخطاء المصادقة** + +- تأكد من أن حساب Google الخاص بك لديه الصلاحيات اللازمة للوصول إلى التقويم +- تحقق من أن اتصال OAuth يتضمن جميع النطاقات المطلوبة لـ Google Calendar API +- تحقق مما إذا كانت إعدادات مشاركة التقويم تسمح بمستوى الوصول المطلوب + +**مشاكل إنشاء الأحداث** + +- تحقق من صحة صيغ الوقت (صيغة RFC3339) +- تأكد من صحة صيغة عناوين البريد الإلكتروني للحضور +- تحقق من وجود التقويم المستهدف وإمكانية الوصول إليه +- تحقق من صحة تحديد المناطق الزمنية + +**التوفر وتعارضات الوقت** + +- استخدم صيغة RFC3339 المناسبة لنطاقات الوقت عند التحقق من التوفر +- تأكد من اتساق المناطق الزمنية عبر جميع العمليات +- تحقق من صحة معرّفات التقاويم عند التحقق من تقاويم متعددة + +**تحديث الأحداث وحذفها** + +- تحقق من صحة معرّفات الأحداث ووجودها +- تأكد من أن لديك صلاحيات التحرير للأحداث +- تحقق من أن ملكية التقويم تسمح بالتعديلات + +### الحصول على المساعدة + + + تواصل مع فريق الدعم للحصول على المساعدة في إعداد تكامل Google Calendar + أو استكشاف الأخطاء وإصلاحها. + diff --git a/docs/ar/enterprise/integrations/google_contacts.mdx b/docs/ar/enterprise/integrations/google_contacts.mdx new file mode 100644 index 000000000..d3627ec83 --- /dev/null +++ b/docs/ar/enterprise/integrations/google_contacts.mdx @@ -0,0 +1,493 @@ +--- +title: تكامل Google Contacts +description: "إدارة جهات الاتصال والدليل مع تكامل Google Contacts لـ CrewAI." +icon: "address-book" +mode: "wide" +--- + +## نظرة عامة + +مكّن وكلاءك من إدارة جهات الاتصال ومعلومات الدليل عبر Google Contacts. يمكنك الوصول إلى جهات الاتصال الشخصية، والبحث في أشخاص الدليل، وإنشاء معلومات الاتصال وتحديثها، وإدارة مجموعات جهات الاتصال باستخدام الأتمتة المدعومة بالذكاء الاصطناعي. + +## المتطلبات الأساسية + +قبل استخدام تكامل Google Contacts، تأكد من توفر ما يلي: + +- حساب [CrewAI AMP](https://app.crewai.com) مع اشتراك فعّال +- حساب Google مع إمكانية الوصول إلى Google Contacts +- ربط حساب Google الخاص بك عبر [صفحة التكاملات](https://app.crewai.com/crewai_plus/connectors) + +## إعداد تكامل Google Contacts + +### 1. ربط حساب Google الخاص بك + +1. انتقل إلى [تكاملات CrewAI AMP](https://app.crewai.com/crewai_plus/connectors) +2. ابحث عن **Google Contacts** في قسم تكاملات المصادقة +3. انقر على **Connect** وأكمل عملية OAuth +4. امنح الصلاحيات اللازمة للوصول إلى جهات الاتصال والدليل +5. انسخ رمز المؤسسة من [إعدادات التكامل](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. تثبيت الحزمة المطلوبة + +```bash +uv add crewai-tools +``` + +### 3. إعداد متغير البيئة + + + لاستخدام التكاملات مع `Agent(apps=[])`, يجب تعيين متغير البيئة + `CREWAI_PLATFORM_INTEGRATION_TOKEN` برمز المؤسسة الخاص بك. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +أو أضفه إلى ملف `.env`: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## الإجراءات المتاحة + + + + **الوصف:** استرجاع جهات اتصال المستخدم من Google Contacts. + + **المعاملات:** + - `pageSize` (integer, اختياري): عدد جهات الاتصال المراد إرجاعها (الحد الأقصى 1000). الحد الأدنى: 1، الحد الأقصى: 1000 + - `pageToken` (string, اختياري): رمز الصفحة المراد استرجاعها. + - `personFields` (string, اختياري): الحقول المراد تضمينها (مثال: 'names,emailAddresses,phoneNumbers'). الافتراضي: names,emailAddresses,phoneNumbers + - `requestSyncToken` (boolean, اختياري): ما إذا كان يجب أن تتضمن الاستجابة رمز مزامنة. الافتراضي: false + - `sortOrder` (string, اختياري): ترتيب الفرز للاتصالات. الخيارات: LAST_MODIFIED_ASCENDING, LAST_MODIFIED_DESCENDING, FIRST_NAME_ASCENDING, LAST_NAME_ASCENDING + + + + + **الوصف:** البحث عن جهات اتصال باستخدام سلسلة استعلام. + + **المعاملات:** + - `query` (string, مطلوب): سلسلة استعلام البحث + - `readMask` (string, مطلوب): الحقول المراد قراءتها (مثال: 'names,emailAddresses,phoneNumbers') + - `pageSize` (integer, اختياري): عدد النتائج المراد إرجاعها. الحد الأدنى: 1، الحد الأقصى: 30 + - `pageToken` (string, اختياري): رمز يحدد صفحة النتائج المراد إرجاعها. + - `sources` (array, اختياري): المصادر المراد البحث فيها. الخيارات: READ_SOURCE_TYPE_CONTACT, READ_SOURCE_TYPE_PROFILE. الافتراضي: READ_SOURCE_TYPE_CONTACT + + + + + **الوصف:** عرض قائمة الأشخاص في دليل المستخدم المصادق عليه. + + **المعاملات:** + - `sources` (array, مطلوب): مصادر الدليل المراد البحث فيها. الخيارات: DIRECTORY_SOURCE_TYPE_DOMAIN_PROFILE, DIRECTORY_SOURCE_TYPE_DOMAIN_CONTACT. الافتراضي: DIRECTORY_SOURCE_TYPE_DOMAIN_PROFILE + - `pageSize` (integer, اختياري): عدد الأشخاص المراد إرجاعهم. الحد الأدنى: 1، الحد الأقصى: 1000 + - `pageToken` (string, اختياري): رمز يحدد صفحة النتائج المراد إرجاعها. + - `readMask` (string, اختياري): الحقول المراد قراءتها (مثال: 'names,emailAddresses') + - `requestSyncToken` (boolean, اختياري): ما إذا كان يجب أن تتضمن الاستجابة رمز مزامنة. الافتراضي: false + - `mergeSources` (array, اختياري): بيانات إضافية لدمجها في استجابات أشخاص الدليل. الخيارات: CONTACT + + + + + **الوصف:** البحث عن أشخاص في الدليل. + + **المعاملات:** + - `query` (string, مطلوب): استعلام البحث + - `sources` (string, مطلوب): مصادر الدليل (استخدم 'DIRECTORY_SOURCE_TYPE_DOMAIN_PROFILE') + - `pageSize` (integer, اختياري): عدد النتائج المراد إرجاعها + - `readMask` (string, اختياري): الحقول المراد قراءتها + + + + + **الوصف:** عرض جهات الاتصال الأخرى (غير الموجودة في جهات الاتصال الشخصية). + + **المعاملات:** + - `pageSize` (integer, اختياري): عدد جهات الاتصال المراد إرجاعها. الحد الأدنى: 1، الحد الأقصى: 1000 + - `pageToken` (string, اختياري): رمز يحدد صفحة النتائج المراد إرجاعها. + - `readMask` (string, اختياري): الحقول المراد قراءتها + - `requestSyncToken` (boolean, اختياري): ما إذا كان يجب أن تتضمن الاستجابة رمز مزامنة. الافتراضي: false + + + + + **الوصف:** البحث في جهات الاتصال الأخرى. + + **المعاملات:** + - `query` (string, مطلوب): استعلام البحث + - `readMask` (string, مطلوب): الحقول المراد قراءتها (مثال: 'names,emailAddresses') + - `pageSize` (integer, اختياري): عدد النتائج + + + + + **الوصف:** الحصول على معلومات الاتصال لشخص واحد بواسطة اسم المورد. + + **المعاملات:** + - `resourceName` (string, مطلوب): اسم المورد للشخص المراد الحصول عليه (مثال: 'people/c123456789') + - `personFields` (string, اختياري): الحقول المراد تضمينها (مثال: 'names,emailAddresses,phoneNumbers'). الافتراضي: names,emailAddresses,phoneNumbers + + + + + **الوصف:** إنشاء جهة اتصال جديدة في دفتر عناوين المستخدم. + + **المعاملات:** + - `names` (array, اختياري): أسماء الشخص + ```json + [ + { + "givenName": "John", + "familyName": "Doe", + "displayName": "John Doe" + } + ] + ``` + - `emailAddresses` (array, اختياري): عناوين البريد الإلكتروني + ```json + [ + { + "value": "john.doe@example.com", + "type": "work" + } + ] + ``` + - `phoneNumbers` (array, اختياري): أرقام الهاتف + ```json + [ + { + "value": "+1234567890", + "type": "mobile" + } + ] + ``` + - `addresses` (array, اختياري): العناوين البريدية + ```json + [ + { + "formattedValue": "123 Main St, City, State 12345", + "type": "home" + } + ] + ``` + - `organizations` (array, اختياري): المؤسسات/الشركات + ```json + [ + { + "name": "Company Name", + "title": "Job Title", + "type": "work" + } + ] + ``` + + + + + **الوصف:** تحديث معلومات جهة اتصال موجودة. + + **المعاملات:** + - `resourceName` (string, مطلوب): اسم المورد للشخص المراد تحديثه (مثال: 'people/c123456789') + - `updatePersonFields` (string, مطلوب): الحقول المراد تحديثها (مثال: 'names,emailAddresses,phoneNumbers') + - `names` (array, اختياري): أسماء الشخص + - `emailAddresses` (array, اختياري): عناوين البريد الإلكتروني + - `phoneNumbers` (array, اختياري): أرقام الهاتف + + + + + **الوصف:** حذف جهة اتصال من دفتر عناوين المستخدم. + + **المعاملات:** + - `resourceName` (string, مطلوب): اسم المورد للشخص المراد حذفه (مثال: 'people/c123456789') + + + + + **الوصف:** الحصول على معلومات عن عدة أشخاص في طلب واحد. + + **المعاملات:** + - `resourceNames` (array, مطلوب): أسماء موارد الأشخاص المراد الحصول عليهم. الحد الأقصى: 200 عنصر + - `personFields` (string, اختياري): الحقول المراد تضمينها (مثال: 'names,emailAddresses,phoneNumbers'). الافتراضي: names,emailAddresses,phoneNumbers + + + + + **الوصف:** عرض مجموعات جهات اتصال المستخدم (التصنيفات). + + **المعاملات:** + - `pageSize` (integer, اختياري): عدد مجموعات جهات الاتصال المراد إرجاعها. الحد الأدنى: 1، الحد الأقصى: 1000 + - `pageToken` (string, اختياري): رمز يحدد صفحة النتائج المراد إرجاعها. + - `groupFields` (string, اختياري): الحقول المراد تضمينها (مثال: 'name,memberCount,clientData'). الافتراضي: name,memberCount + + + + + **الوصف:** الحصول على مجموعة جهات اتصال محددة بواسطة اسم المورد. + + **المعاملات:** + - `resourceName` (string, مطلوب): اسم المورد لمجموعة جهات الاتصال (مثال: 'contactGroups/myContactGroup') + - `maxMembers` (integer, اختياري): الحد الأقصى لعدد الأعضاء المراد تضمينهم. الحد الأدنى: 0، الحد الأقصى: 20000 + - `groupFields` (string, اختياري): الحقول المراد تضمينها (مثال: 'name,memberCount,clientData'). الافتراضي: name,memberCount + + + + + **الوصف:** إنشاء مجموعة جهات اتصال جديدة (تصنيف). + + **المعاملات:** + - `name` (string, مطلوب): اسم مجموعة جهات الاتصال + - `clientData` (array, اختياري): بيانات خاصة بالعميل + ```json + [ + { + "key": "data_key", + "value": "data_value" + } + ] + ``` + + + + + **الوصف:** تحديث معلومات مجموعة جهات اتصال. + + **المعاملات:** + - `resourceName` (string, مطلوب): اسم المورد لمجموعة جهات الاتصال (مثال: 'contactGroups/myContactGroup') + - `name` (string, مطلوب): اسم مجموعة جهات الاتصال + - `clientData` (array, اختياري): بيانات خاصة بالعميل + ```json + [ + { + "key": "data_key", + "value": "data_value" + } + ] + ``` + + + + + **الوصف:** حذف مجموعة جهات اتصال. + + **المعاملات:** + - `resourceName` (string, مطلوب): اسم المورد لمجموعة جهات الاتصال المراد حذفها (مثال: 'contactGroups/myContactGroup') + - `deleteContacts` (boolean, اختياري): ما إذا كان يجب حذف جهات الاتصال في المجموعة أيضاً. الافتراضي: false + + + + +## أمثلة الاستخدام + +### إعداد Agent أساسي لـ Google Contacts + +```python +from crewai import Agent, Task, Crew + +# Create an agent with Google Contacts capabilities +contacts_agent = Agent( + role="Contact Manager", + goal="Manage contacts and directory information efficiently", + backstory="An AI assistant specialized in contact management and directory operations.", + apps=['google_contacts'] # All Google Contacts actions will be available +) + +# Task to retrieve and organize contacts +contact_management_task = Task( + description="Retrieve all contacts and organize them by company affiliation", + agent=contacts_agent, + expected_output="Contacts retrieved and organized by company with summary report" +) + +# Run the task +crew = Crew( + agents=[contacts_agent], + tasks=[contact_management_task] +) + +crew.kickoff() +``` + +### البحث في الدليل وإدارته + +```python +from crewai import Agent, Task, Crew + +directory_manager = Agent( + role="Directory Manager", + goal="Search and manage directory people and contacts", + backstory="An AI assistant that specializes in directory management and people search.", + apps=[ + 'google_contacts/search_directory_people', + 'google_contacts/list_directory_people', + 'google_contacts/search_contacts' + ] +) + +# Task to search and manage directory +directory_task = Task( + description="Search for team members in the company directory and create a team contact list", + agent=directory_manager, + expected_output="Team directory compiled with contact information" +) + +crew = Crew( + agents=[directory_manager], + tasks=[directory_task] +) + +crew.kickoff() +``` + +### إنشاء جهات الاتصال وتحديثاتها + +```python +from crewai import Agent, Task, Crew + +contact_curator = Agent( + role="Contact Curator", + goal="Create and update contact information systematically", + backstory="An AI assistant that maintains accurate and up-to-date contact information.", + apps=['google_contacts'] +) + +# Task to create and update contacts +curation_task = Task( + description=""" + 1. Search for existing contacts related to new business partners + 2. Create new contacts for partners not in the system + 3. Update existing contact information with latest details + 4. Organize contacts into appropriate groups + """, + agent=contact_curator, + expected_output="Contact database updated with new partners and organized groups" +) + +crew = Crew( + agents=[contact_curator], + tasks=[curation_task] +) + +crew.kickoff() +``` + +### إدارة مجموعات جهات الاتصال + +```python +from crewai import Agent, Task, Crew + +group_organizer = Agent( + role="Contact Group Organizer", + goal="Organize contacts into meaningful groups and categories", + backstory="An AI assistant that specializes in contact organization and group management.", + apps=['google_contacts'] +) + +# Task to organize contact groups +organization_task = Task( + description=""" + 1. List all existing contact groups + 2. Analyze contact distribution across groups + 3. Create new groups for better organization + 4. Move contacts to appropriate groups based on their information + """, + agent=group_organizer, + expected_output="Contacts organized into logical groups with improved structure" +) + +crew = Crew( + agents=[group_organizer], + tasks=[organization_task] +) + +crew.kickoff() +``` + +### إدارة جهات الاتصال الشاملة + +```python +from crewai import Agent, Task, Crew + +contact_specialist = Agent( + role="Contact Management Specialist", + goal="Provide comprehensive contact management across all sources", + backstory="An AI assistant that handles all aspects of contact management including personal, directory, and other contacts.", + apps=['google_contacts'] +) + +# Complex contact management task +comprehensive_task = Task( + description=""" + 1. Retrieve contacts from all sources (personal, directory, other) + 2. Search for duplicate contacts and merge information + 3. Update outdated contact information + 4. Create missing contacts for important stakeholders + 5. Organize contacts into meaningful groups + 6. Generate a comprehensive contact report + """, + agent=contact_specialist, + expected_output="Complete contact management performed with unified contact database and detailed report" +) + +crew = Crew( + agents=[contact_specialist], + tasks=[comprehensive_task] +) + +crew.kickoff() +``` + +## استكشاف الأخطاء وإصلاحها + +### المشاكل الشائعة + +**أخطاء الصلاحيات** + +- تأكد من أن حساب Google الخاص بك لديه الصلاحيات المناسبة للوصول إلى جهات الاتصال +- تحقق من أن اتصال OAuth يتضمن النطاقات المطلوبة لـ Google Contacts API +- تحقق من منح صلاحيات الوصول للدليل لجهات اتصال المؤسسة + +**مشاكل صيغة اسم المورد** + +- تأكد من أن أسماء الموارد تتبع الصيغة الصحيحة (مثال: 'people/c123456789' لجهات الاتصال) +- تحقق من أن أسماء موارد مجموعات جهات الاتصال تستخدم الصيغة 'contactGroups/groupId' +- تأكد من وجود أسماء الموارد وإمكانية الوصول إليها + +**مشاكل البحث والاستعلام** + +- تأكد من صحة صيغة استعلامات البحث وعدم كونها فارغة +- استخدم حقول readMask المناسبة للبيانات التي تحتاجها +- تحقق من صحة تحديد مصادر البحث (جهات اتصال مقابل ملفات تعريف) + +**إنشاء جهات الاتصال وتحديثاتها** + +- تأكد من توفير الحقول المطلوبة عند إنشاء جهات الاتصال +- تحقق من صحة صيغة عناوين البريد الإلكتروني وأرقام الهاتف +- تأكد من أن معامل updatePersonFields يتضمن جميع الحقول التي يتم تحديثها + +**مشاكل الوصول إلى الدليل** + +- تأكد من أن لديك الصلاحيات المناسبة للوصول إلى دليل المؤسسة +- تحقق من صحة تحديد مصادر الدليل +- تأكد من أن مؤسستك تسمح بالوصول عبر API إلى معلومات الدليل + +**الترقيم والحدود** + +- انتبه لحدود حجم الصفحة (تختلف حسب نقطة النهاية) +- استخدم pageToken للترقيم عبر مجموعات النتائج الكبيرة +- احترم حدود معدل API وطبّق تأخيرات مناسبة + +**مجموعات جهات الاتصال والتنظيم** + +- تأكد من أن أسماء مجموعات جهات الاتصال فريدة عند إنشاء مجموعات جديدة +- تحقق من وجود جهات الاتصال قبل إضافتها إلى المجموعات +- تأكد من أن لديك صلاحيات تعديل مجموعات جهات الاتصال + +### الحصول على المساعدة + + + تواصل مع فريق الدعم للحصول على المساعدة في إعداد تكامل Google Contacts + أو استكشاف الأخطاء وإصلاحها. + diff --git a/docs/ar/enterprise/integrations/google_docs.mdx b/docs/ar/enterprise/integrations/google_docs.mdx new file mode 100644 index 000000000..ea1cc4caf --- /dev/null +++ b/docs/ar/enterprise/integrations/google_docs.mdx @@ -0,0 +1,550 @@ +--- +title: تكامل Google Docs +description: "إنشاء المستندات وتحريرها مع تكامل Google Docs لـ CrewAI." +icon: "file-lines" +mode: "wide" +--- + +## نظرة عامة + +مكّن وكلاءك من إنشاء وتحرير وإدارة مستندات Google Docs مع معالجة النصوص والتنسيق. أتمت إنشاء المستندات، وأدرج النصوص واستبدلها، وأدر نطاقات المحتوى، وبسّط سير عمل المستندات باستخدام الأتمتة المدعومة بالذكاء الاصطناعي. + +## المتطلبات الأساسية + +قبل استخدام تكامل Google Docs، تأكد من توفر ما يلي: + +- حساب [CrewAI AMP](https://app.crewai.com) مع اشتراك فعّال +- حساب Google مع إمكانية الوصول إلى Google Docs +- ربط حساب Google الخاص بك عبر [صفحة التكاملات](https://app.crewai.com/crewai_plus/connectors) + +## إعداد تكامل Google Docs + +### 1. ربط حساب Google الخاص بك + +1. انتقل إلى [تكاملات CrewAI AMP](https://app.crewai.com/crewai_plus/connectors) +2. ابحث عن **Google Docs** في قسم تكاملات المصادقة +3. انقر على **Connect** وأكمل عملية OAuth +4. امنح الصلاحيات اللازمة للوصول إلى المستندات +5. انسخ رمز المؤسسة من [إعدادات التكامل](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. تثبيت الحزمة المطلوبة + +```bash +uv add crewai-tools +``` + +### 3. إعداد متغير البيئة + + + لاستخدام التكاملات مع `Agent(apps=[])`, يجب تعيين متغير البيئة + `CREWAI_PLATFORM_INTEGRATION_TOKEN` برمز المؤسسة الخاص بك. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +أو أضفه إلى ملف `.env`: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## الإجراءات المتاحة + + + + **الوصف:** إنشاء مستند Google جديد. + + **المعاملات:** + - `title` (string, اختياري): عنوان المستند الجديد. + + + + + **الوصف:** الحصول على محتويات وبيانات وصفية لمستند Google. + + **المعاملات:** + - `documentId` (string, مطلوب): معرّف المستند المراد استرجاعه. + - `includeTabsContent` (boolean, اختياري): ما إذا كان يجب تضمين محتوى علامات التبويب. الافتراضي هو `false`. + - `suggestionsViewMode` (string, اختياري): وضع عرض الاقتراحات المراد تطبيقه. القيم: `DEFAULT_FOR_CURRENT_ACCESS`, `PREVIEW_SUGGESTIONS_ACCEPTED`, `PREVIEW_WITHOUT_SUGGESTIONS`. الافتراضي: `DEFAULT_FOR_CURRENT_ACCESS`. + + + + + **الوصف:** تطبيق تحديث واحد أو أكثر على مستند Google. + + **المعاملات:** + - `documentId` (string, مطلوب): معرّف المستند المراد تحديثه. + - `requests` (array, مطلوب): قائمة بالتحديثات المراد تطبيقها على المستند. + - `writeControl` (object, اختياري): يوفر التحكم في كيفية تنفيذ طلبات الكتابة. + + + + + **الوصف:** إدراج نص في مستند Google في موقع محدد. + + **المعاملات:** + - `documentId` (string, مطلوب): معرّف المستند المراد تحديثه. + - `text` (string, مطلوب): النص المراد إدراجه. + - `index` (integer, اختياري): الفهرس القائم على الصفر حيث يتم إدراج النص. الافتراضي هو `1`. + + + + + **الوصف:** استبدال جميع نُسخ النص في مستند Google. + + **المعاملات:** + - `documentId` (string, مطلوب): معرّف المستند المراد تحديثه. + - `containsText` (string, مطلوب): النص المراد البحث عنه واستبداله. + - `replaceText` (string, مطلوب): النص البديل. + - `matchCase` (boolean, اختياري): ما إذا كان البحث يجب أن يراعي حالة الأحرف. الافتراضي هو `false`. + + + + + **الوصف:** حذف المحتوى من نطاق محدد في مستند Google. + + **المعاملات:** + - `documentId` (string, مطلوب): معرّف المستند المراد تحديثه. + - `startIndex` (integer, مطلوب): فهرس بداية النطاق المراد حذفه. + - `endIndex` (integer, مطلوب): فهرس نهاية النطاق المراد حذفه. + + + + + **الوصف:** إدراج فاصل صفحة في موقع محدد في مستند Google. + + **المعاملات:** + - `documentId` (string, مطلوب): معرّف المستند المراد تحديثه. + - `index` (integer, اختياري): الفهرس القائم على الصفر حيث يتم إدراج فاصل الصفحة. الافتراضي هو `1`. + + + + + **الوصف:** إنشاء نطاق مسمّى في مستند Google. + + **المعاملات:** + - `documentId` (string, مطلوب): معرّف المستند المراد تحديثه. + - `name` (string, مطلوب): اسم النطاق المسمّى. + - `startIndex` (integer, مطلوب): فهرس بداية النطاق. + - `endIndex` (integer, مطلوب): فهرس نهاية النطاق. + + + + + **الوصف:** إنشاء مستند Google جديد مع محتوى في إجراء واحد. + + **المعاملات:** + - `title` (string, مطلوب): عنوان المستند الجديد. + - `content` (string, اختياري): المحتوى النصي المراد إدراجه في المستند. استخدم `\n` لفقرات جديدة. + + + + + **الوصف:** إلحاق نص بنهاية مستند Google. يُدرج تلقائياً في نهاية المستند دون الحاجة لتحديد فهرس. + + **المعاملات:** + - `documentId` (string, مطلوب): معرّف المستند. + - `text` (string, مطلوب): النص المراد إلحاقه بنهاية المستند. استخدم `\n` لفقرات جديدة. + + + + + **الوصف:** جعل النص غامقاً أو إزالة التنسيق الغامق في مستند Google. + + **المعاملات:** + - `documentId` (string, مطلوب): معرّف المستند. + - `startIndex` (integer, مطلوب): موضع بداية النص المراد تنسيقه. + - `endIndex` (integer, مطلوب): موضع نهاية النص المراد تنسيقه (حصري). + - `bold` (boolean, مطلوب): عيّن `true` لجعله غامقاً، `false` لإزالة الغامق. + + + + + **الوصف:** جعل النص مائلاً أو إزالة التنسيق المائل في مستند Google. + + **المعاملات:** + - `documentId` (string, مطلوب): معرّف المستند. + - `startIndex` (integer, مطلوب): موضع بداية النص المراد تنسيقه. + - `endIndex` (integer, مطلوب): موضع نهاية النص المراد تنسيقه (حصري). + - `italic` (boolean, مطلوب): عيّن `true` لجعله مائلاً، `false` لإزالة المائل. + + + + + **الوصف:** إضافة أو إزالة تنسيق التسطير من النص في مستند Google. + + **المعاملات:** + - `documentId` (string, مطلوب): معرّف المستند. + - `startIndex` (integer, مطلوب): موضع بداية النص المراد تنسيقه. + - `endIndex` (integer, مطلوب): موضع نهاية النص المراد تنسيقه (حصري). + - `underline` (boolean, مطلوب): عيّن `true` للتسطير، `false` لإزالة التسطير. + + + + + **الوصف:** إضافة أو إزالة تنسيق يتوسطه خط من النص في مستند Google. + + **المعاملات:** + - `documentId` (string, مطلوب): معرّف المستند. + - `startIndex` (integer, مطلوب): موضع بداية النص المراد تنسيقه. + - `endIndex` (integer, مطلوب): موضع نهاية النص المراد تنسيقه (حصري). + - `strikethrough` (boolean, مطلوب): عيّن `true` لإضافة يتوسطه خط، `false` للإزالة. + + + + + **الوصف:** تغيير حجم خط النص في مستند Google. + + **المعاملات:** + - `documentId` (string, مطلوب): معرّف المستند. + - `startIndex` (integer, مطلوب): موضع بداية النص المراد تنسيقه. + - `endIndex` (integer, مطلوب): موضع نهاية النص المراد تنسيقه (حصري). + - `fontSize` (number, مطلوب): حجم الخط بالنقاط. الأحجام الشائعة: 10, 11, 12, 14, 16, 18, 24, 36. + + + + + **الوصف:** تغيير لون النص باستخدام قيم RGB (مقياس 0-1) في مستند Google. + + **المعاملات:** + - `documentId` (string, مطلوب): معرّف المستند. + - `startIndex` (integer, مطلوب): موضع بداية النص المراد تنسيقه. + - `endIndex` (integer, مطلوب): موضع نهاية النص المراد تنسيقه (حصري). + - `red` (number, مطلوب): مكوّن الأحمر (0-1). مثال: `1` للأحمر الكامل. + - `green` (number, مطلوب): مكوّن الأخضر (0-1). مثال: `0.5` لنصف الأخضر. + - `blue` (number, مطلوب): مكوّن الأزرق (0-1). مثال: `0` لعدم وجود أزرق. + + + + + **الوصف:** تحويل نص موجود إلى رابط قابل للنقر في مستند Google. + + **المعاملات:** + - `documentId` (string, مطلوب): معرّف المستند. + - `startIndex` (integer, مطلوب): موضع بداية النص المراد تحويله إلى رابط. + - `endIndex` (integer, مطلوب): موضع نهاية النص المراد تحويله إلى رابط (حصري). + - `url` (string, مطلوب): عنوان URL الذي يجب أن يشير إليه الرابط. مثال: `"https://example.com"`. + + + + + **الوصف:** تطبيق نمط عنوان أو فقرة على نطاق نصي في مستند Google. + + **المعاملات:** + - `documentId` (string, مطلوب): معرّف المستند. + - `startIndex` (integer, مطلوب): موضع بداية الفقرة (الفقرات) المراد تنسيقها. + - `endIndex` (integer, مطلوب): موضع نهاية الفقرة (الفقرات) المراد تنسيقها. + - `style` (string, مطلوب): النمط المراد تطبيقه. القيم: `NORMAL_TEXT`, `TITLE`, `SUBTITLE`, `HEADING_1`, `HEADING_2`, `HEADING_3`, `HEADING_4`, `HEADING_5`, `HEADING_6`. + + + + + **الوصف:** تعيين محاذاة النص للفقرات في مستند Google. + + **المعاملات:** + - `documentId` (string, مطلوب): معرّف المستند. + - `startIndex` (integer, مطلوب): موضع بداية الفقرة (الفقرات) المراد محاذاتها. + - `endIndex` (integer, مطلوب): موضع نهاية الفقرة (الفقرات) المراد محاذاتها. + - `alignment` (string, مطلوب): محاذاة النص. القيم: `START` (يسار), `CENTER`, `END` (يمين), `JUSTIFIED`. + + + + + **الوصف:** تعيين تباعد الأسطر للفقرات في مستند Google. + + **المعاملات:** + - `documentId` (string, مطلوب): معرّف المستند. + - `startIndex` (integer, مطلوب): موضع بداية الفقرة (الفقرات). + - `endIndex` (integer, مطلوب): موضع نهاية الفقرة (الفقرات). + - `lineSpacing` (number, مطلوب): تباعد الأسطر كنسبة مئوية. `100` = مفرد، `115` = 1.15x، `150` = 1.5x، `200` = مزدوج. + + + + + **الوصف:** تحويل الفقرات إلى قائمة نقطية أو مرقمة في مستند Google. + + **المعاملات:** + - `documentId` (string, مطلوب): معرّف المستند. + - `startIndex` (integer, مطلوب): موضع بداية الفقرات المراد تحويلها إلى قائمة. + - `endIndex` (integer, مطلوب): موضع نهاية الفقرات المراد تحويلها إلى قائمة. + - `bulletPreset` (string, مطلوب): نمط النقاط/الترقيم. القيم: `BULLET_DISC_CIRCLE_SQUARE`, `BULLET_DIAMONDX_ARROW3D_SQUARE`, `BULLET_CHECKBOX`, `BULLET_ARROW_DIAMOND_DISC`, `BULLET_STAR_CIRCLE_SQUARE`, `NUMBERED_DECIMAL_ALPHA_ROMAN`, `NUMBERED_DECIMAL_ALPHA_ROMAN_PARENS`, `NUMBERED_DECIMAL_NESTED`, `NUMBERED_UPPERALPHA_ALPHA_ROMAN`, `NUMBERED_UPPERROMAN_UPPERALPHA_DECIMAL`. + + + + + **الوصف:** إزالة النقاط أو الترقيم من الفقرات في مستند Google. + + **المعاملات:** + - `documentId` (string, مطلوب): معرّف المستند. + - `startIndex` (integer, مطلوب): موضع بداية فقرات القائمة. + - `endIndex` (integer, مطلوب): موضع نهاية فقرات القائمة. + + + + + **الوصف:** إدراج جدول مع محتوى في مستند Google في إجراء واحد. قدم المحتوى كمصفوفة ثنائية الأبعاد. + + **المعاملات:** + - `documentId` (string, مطلوب): معرّف المستند. + - `rows` (integer, مطلوب): عدد الصفوف في الجدول. + - `columns` (integer, مطلوب): عدد الأعمدة في الجدول. + - `index` (integer, اختياري): الموضع لإدراج الجدول. إذا لم يُحدد، يُدرج الجدول في نهاية المستند. + - `content` (array, مطلوب): محتوى الجدول كمصفوفة ثنائية الأبعاد. كل مصفوفة داخلية هي صف. مثال: `[["Year", "Revenue"], ["2023", "$43B"], ["2024", "$45B"]]`. + + + + + **الوصف:** إدراج صف جديد فوق أو أسفل خلية مرجعية في جدول موجود. + + **المعاملات:** + - `documentId` (string, مطلوب): معرّف المستند. + - `tableStartIndex` (integer, مطلوب): فهرس بداية الجدول. + - `rowIndex` (integer, مطلوب): فهرس الصف (قائم على الصفر) للخلية المرجعية. + - `columnIndex` (integer, اختياري): فهرس العمود (قائم على الصفر) للخلية المرجعية. الافتراضي هو `0`. + - `insertBelow` (boolean, اختياري): إذا `true`، يُدرج أسفل الصف المرجعي. إذا `false`، يُدرج فوقه. الافتراضي هو `true`. + + + + + **الوصف:** إدراج عمود جديد يساراً أو يميناً لخلية مرجعية في جدول موجود. + + **المعاملات:** + - `documentId` (string, مطلوب): معرّف المستند. + - `tableStartIndex` (integer, مطلوب): فهرس بداية الجدول. + - `rowIndex` (integer, اختياري): فهرس الصف (قائم على الصفر) للخلية المرجعية. الافتراضي هو `0`. + - `columnIndex` (integer, مطلوب): فهرس العمود (قائم على الصفر) للخلية المرجعية. + - `insertRight` (boolean, اختياري): إذا `true`، يُدرج إلى اليمين. إذا `false`، يُدرج إلى اليسار. الافتراضي هو `true`. + + + + + **الوصف:** حذف صف من جدول موجود في مستند Google. + + **المعاملات:** + - `documentId` (string, مطلوب): معرّف المستند. + - `tableStartIndex` (integer, مطلوب): فهرس بداية الجدول. + - `rowIndex` (integer, مطلوب): فهرس الصف (قائم على الصفر) المراد حذفه. + - `columnIndex` (integer, اختياري): فهرس العمود (قائم على الصفر) لأي خلية في الصف. الافتراضي هو `0`. + + + + + **الوصف:** حذف عمود من جدول موجود في مستند Google. + + **المعاملات:** + - `documentId` (string, مطلوب): معرّف المستند. + - `tableStartIndex` (integer, مطلوب): فهرس بداية الجدول. + - `rowIndex` (integer, اختياري): فهرس الصف (قائم على الصفر) لأي خلية في العمود. الافتراضي هو `0`. + - `columnIndex` (integer, مطلوب): فهرس العمود (قائم على الصفر) المراد حذفه. + + + + + **الوصف:** دمج نطاق من خلايا الجدول في خلية واحدة. يتم الاحتفاظ بمحتوى جميع الخلايا. + + **المعاملات:** + - `documentId` (string, مطلوب): معرّف المستند. + - `tableStartIndex` (integer, مطلوب): فهرس بداية الجدول. + - `rowIndex` (integer, مطلوب): فهرس الصف البادئ (قائم على الصفر) للدمج. + - `columnIndex` (integer, مطلوب): فهرس العمود البادئ (قائم على الصفر) للدمج. + - `rowSpan` (integer, مطلوب): عدد الصفوف المراد دمجها. + - `columnSpan` (integer, مطلوب): عدد الأعمدة المراد دمجها. + + + + + **الوصف:** إلغاء دمج خلايا جدول مدمجة سابقاً وإعادتها إلى خلايا فردية. + + **المعاملات:** + - `documentId` (string, مطلوب): معرّف المستند. + - `tableStartIndex` (integer, مطلوب): فهرس بداية الجدول. + - `rowIndex` (integer, مطلوب): فهرس الصف (قائم على الصفر) للخلية المدمجة. + - `columnIndex` (integer, مطلوب): فهرس العمود (قائم على الصفر) للخلية المدمجة. + - `rowSpan` (integer, مطلوب): عدد الصفوف التي تمتد عليها الخلية المدمجة. + - `columnSpan` (integer, مطلوب): عدد الأعمدة التي تمتد عليها الخلية المدمجة. + + + + + **الوصف:** إدراج صورة من عنوان URL عام في مستند Google. يجب أن تكون الصورة متاحة للعموم، وأقل من 50 ميجابايت، وبصيغة PNG/JPEG/GIF. + + **المعاملات:** + - `documentId` (string, مطلوب): معرّف المستند. + - `uri` (string, مطلوب): عنوان URL العام للصورة. يجب أن يكون متاحاً بدون مصادقة. + - `index` (integer, اختياري): الموضع لإدراج الصورة. إذا لم يُحدد، تُدرج الصورة في نهاية المستند. الافتراضي هو `1`. + + + + + **الوصف:** إدراج فاصل قسم لإنشاء أقسام مستند بتنسيقات مختلفة. + + **المعاملات:** + - `documentId` (string, مطلوب): معرّف المستند. + - `index` (integer, مطلوب): الموضع لإدراج فاصل القسم. + - `sectionType` (string, مطلوب): نوع فاصل القسم. القيم: `CONTINUOUS` (يبقى في نفس الصفحة), `NEXT_PAGE` (يبدأ صفحة جديدة). + + + + + **الوصف:** إنشاء ترويسة للمستند. يُرجع headerId يمكن استخدامه مع insert_text لإضافة محتوى الترويسة. + + **المعاملات:** + - `documentId` (string, مطلوب): معرّف المستند. + - `type` (string, اختياري): نوع الترويسة. القيم: `DEFAULT`. الافتراضي هو `DEFAULT`. + + + + + **الوصف:** إنشاء تذييل للمستند. يُرجع footerId يمكن استخدامه مع insert_text لإضافة محتوى التذييل. + + **المعاملات:** + - `documentId` (string, مطلوب): معرّف المستند. + - `type` (string, اختياري): نوع التذييل. القيم: `DEFAULT`. الافتراضي هو `DEFAULT`. + + + + + **الوصف:** حذف ترويسة من المستند. استخدم get_document للعثور على headerId. + + **المعاملات:** + - `documentId` (string, مطلوب): معرّف المستند. + - `headerId` (string, مطلوب): معرّف الترويسة المراد حذفها. + + + + + **الوصف:** حذف تذييل من المستند. استخدم get_document للعثور على footerId. + + **المعاملات:** + - `documentId` (string, مطلوب): معرّف المستند. + - `footerId` (string, مطلوب): معرّف التذييل المراد حذفه. + + + + +## أمثلة الاستخدام + +### إعداد Agent أساسي لـ Google Docs + +```python +from crewai import Agent, Task, Crew + +# Create an agent with Google Docs capabilities +docs_agent = Agent( + role="Document Creator", + goal="Create and manage Google Docs documents efficiently", + backstory="An AI assistant specialized in Google Docs document creation and editing.", + apps=['google_docs'] # All Google Docs actions will be available +) + +# Task to create a new document +create_doc_task = Task( + description="Create a new Google Document titled 'Project Status Report'", + agent=docs_agent, + expected_output="New Google Document 'Project Status Report' created successfully" +) + +# Run the task +crew = Crew( + agents=[docs_agent], + tasks=[create_doc_task] +) + +crew.kickoff() +``` + +### تحرير النصوص وإدارة المحتوى + +```python +from crewai import Agent, Task, Crew + +# Create an agent focused on text editing +text_editor = Agent( + role="Document Editor", + goal="Edit and update content in Google Docs documents", + backstory="An AI assistant skilled in precise text editing and content management.", + apps=['google_docs/insert_text', 'google_docs/replace_text', 'google_docs/delete_content_range'] +) + +# Task to edit document content +edit_content_task = Task( + description="In document 'your_document_id', insert the text 'Executive Summary: ' at the beginning, then replace all instances of 'TODO' with 'COMPLETED'.", + agent=text_editor, + expected_output="Document updated with new text inserted and TODO items replaced." +) + +crew = Crew( + agents=[text_editor], + tasks=[edit_content_task] +) + +crew.kickoff() +``` + +### عمليات المستندات المتقدمة + +```python +from crewai import Agent, Task, Crew + +# Create an agent for advanced document operations +document_formatter = Agent( + role="Document Formatter", + goal="Apply advanced formatting and structure to Google Docs", + backstory="An AI assistant that handles complex document formatting and organization.", + apps=['google_docs/batch_update', 'google_docs/insert_page_break', 'google_docs/create_named_range'] +) + +# Task to format document +format_doc_task = Task( + description="In document 'your_document_id', insert a page break at position 100, create a named range called 'Introduction' for characters 1-50, and apply batch formatting updates.", + agent=document_formatter, + expected_output="Document formatted with page break, named range, and styling applied." +) + +crew = Crew( + agents=[document_formatter], + tasks=[format_doc_task] +) + +crew.kickoff() +``` + +## استكشاف الأخطاء وإصلاحها + +### المشاكل الشائعة + +**أخطاء المصادقة** + +- تأكد من أن حساب Google الخاص بك لديه الصلاحيات اللازمة للوصول إلى Google Docs. +- تحقق من أن اتصال OAuth يتضمن جميع النطاقات المطلوبة (`https://www.googleapis.com/auth/documents`). + +**مشاكل معرّف المستند** + +- تحقق جيداً من صحة معرّفات المستندات. +- تأكد من وجود المستند وإمكانية الوصول إليه من حسابك. +- يمكن العثور على معرّفات المستندات في عنوان URL لـ Google Docs. + +**عمليات إدراج النص والنطاقات** + +- عند استخدام `insert_text` أو `delete_content_range`، تأكد من صحة مواضع الفهرس. +- تذكر أن Google Docs يستخدم فهرسة قائمة على الصفر. +- يجب أن يحتوي المستند على محتوى في مواضع الفهرس المحددة. + +**تنسيق طلبات التحديث الدفعي** + +- عند استخدام `batch_update`، تأكد من صحة تنسيق مصفوفة `requests` وفقاً لتوثيق Google Docs API. +- تتطلب التحديثات المعقدة هياكل JSON محددة لكل نوع طلب. + +**عمليات استبدال النص** + +- لـ `replace_text`، تأكد من مطابقة معامل `containsText` تماماً للنص المراد استبداله. +- استخدم معامل `matchCase` للتحكم في حساسية حالة الأحرف. + +### الحصول على المساعدة + + + تواصل مع فريق الدعم للحصول على المساعدة في إعداد تكامل Google Docs أو + استكشاف الأخطاء وإصلاحها. + diff --git a/docs/ar/enterprise/integrations/google_drive.mdx b/docs/ar/enterprise/integrations/google_drive.mdx new file mode 100644 index 000000000..18b8a3371 --- /dev/null +++ b/docs/ar/enterprise/integrations/google_drive.mdx @@ -0,0 +1,238 @@ +--- +title: تكامل Google Drive +description: "تخزين الملفات وإدارتها مع تكامل Google Drive لـ CrewAI." +icon: "google" +mode: "wide" +--- + +## نظرة عامة + +مكّن وكلاءك من إدارة الملفات والمجلدات عبر Google Drive. ارفع الملفات وحمّلها ونظّمها وشاركها، وأنشئ المجلدات، وبسّط سير عمل إدارة المستندات باستخدام الأتمتة المدعومة بالذكاء الاصطناعي. + +## المتطلبات الأساسية + +قبل استخدام تكامل Google Drive، تأكد من توفر ما يلي: + +- حساب [CrewAI AMP](https://app.crewai.com) مع اشتراك فعّال +- حساب Google مع إمكانية الوصول إلى Google Drive +- ربط حساب Google الخاص بك عبر [صفحة التكاملات](https://app.crewai.com/crewai_plus/connectors) + +## إعداد تكامل Google Drive + +### 1. ربط حساب Google الخاص بك + +1. انتقل إلى [تكاملات CrewAI AMP](https://app.crewai.com/crewai_plus/connectors) +2. ابحث عن **Google Drive** في قسم تكاملات المصادقة +3. انقر على **Connect** وأكمل عملية OAuth +4. امنح الصلاحيات اللازمة لإدارة الملفات والمجلدات +5. انسخ رمز المؤسسة من [إعدادات التكامل](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. تثبيت الحزمة المطلوبة + +```bash +uv add crewai-tools +``` + +### 3. إعداد متغير البيئة + + + لاستخدام التكاملات مع `Agent(apps=[])`, يجب تعيين متغير البيئة + `CREWAI_PLATFORM_INTEGRATION_TOKEN` برمز المؤسسة الخاص بك. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +أو أضفه إلى ملف `.env`: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## الإجراءات المتاحة + + + + **الوصف:** الحصول على ملف بواسطة المعرّف من Google Drive. + + **المعاملات:** + - `file_id` (string, مطلوب): معرّف الملف المراد استرجاعه. + + + + + **الوصف:** عرض قائمة الملفات في Google Drive. + + **المعاملات:** + - `q` (string, اختياري): سلسلة استعلام لتصفية الملفات (مثال: "name contains 'report'"). + - `page_size` (integer, اختياري): الحد الأقصى لعدد الملفات المُرجعة (الافتراضي: 100، الحد الأقصى: 1000). + - `page_token` (string, اختياري): رمز لاسترجاع الصفحة التالية من النتائج. + - `order_by` (string, اختياري): ترتيب الفرز (مثال: "name", "createdTime desc", "modifiedTime"). + - `spaces` (string, اختياري): قائمة مفصولة بفواصل للمساحات المراد الاستعلام عنها (drive, appDataFolder, photos). + + + + + **الوصف:** رفع ملف إلى Google Drive. + + **المعاملات:** + - `name` (string, مطلوب): اسم الملف المراد إنشاؤه. + - `content` (string, مطلوب): محتوى الملف المراد رفعه. + - `mime_type` (string, اختياري): نوع MIME للملف (مثال: "text/plain", "application/pdf"). + - `parent_folder_id` (string, اختياري): معرّف المجلد الأصلي حيث يجب إنشاء الملف. + - `description` (string, اختياري): وصف الملف. + + + + + **الوصف:** تحميل ملف من Google Drive. + + **المعاملات:** + - `file_id` (string, مطلوب): معرّف الملف المراد تحميله. + - `mime_type` (string, اختياري): نوع MIME للتصدير (مطلوب لمستندات Google Workspace). + + + + + **الوصف:** إنشاء مجلد جديد في Google Drive. + + **المعاملات:** + - `name` (string, مطلوب): اسم المجلد المراد إنشاؤه. + - `parent_folder_id` (string, اختياري): معرّف المجلد الأصلي حيث يجب إنشاء المجلد الجديد. + - `description` (string, اختياري): وصف المجلد. + + + + + **الوصف:** حذف ملف من Google Drive. + + **المعاملات:** + - `file_id` (string, مطلوب): معرّف الملف المراد حذفه. + + + + + **الوصف:** مشاركة ملف في Google Drive مع مستخدمين محددين أو جعله عاماً. + + **المعاملات:** + - `file_id` (string, مطلوب): معرّف الملف المراد مشاركته. + - `role` (string, مطلوب): الدور الممنوح بهذا الإذن (reader, writer, commenter, owner). + - `type` (string, مطلوب): نوع المستفيد (user, group, domain, anyone). + - `email_address` (string, اختياري): عنوان البريد الإلكتروني للمستخدم أو المجموعة المراد المشاركة معهم (مطلوب لأنواع user/group). + - `domain` (string, اختياري): النطاق المراد المشاركة معه (مطلوب لنوع domain). + - `send_notification_email` (boolean, اختياري): ما إذا كان يجب إرسال بريد إلكتروني إشعاري (الافتراضي: true). + - `email_message` (string, اختياري): رسالة نصية مخصصة لتضمينها في البريد الإلكتروني الإشعاري. + + + + + **الوصف:** تحديث ملف موجود في Google Drive. + + **المعاملات:** + - `file_id` (string, مطلوب): معرّف الملف المراد تحديثه. + - `name` (string, اختياري): الاسم الجديد للملف. + - `content` (string, اختياري): المحتوى الجديد للملف. + - `mime_type` (string, اختياري): نوع MIME الجديد للملف. + - `description` (string, اختياري): الوصف الجديد للملف. + - `add_parents` (string, اختياري): قائمة مفصولة بفواصل لمعرّفات المجلدات الأصلية المراد إضافتها. + - `remove_parents` (string, اختياري): قائمة مفصولة بفواصل لمعرّفات المجلدات الأصلية المراد إزالتها. + + + + +## أمثلة الاستخدام + +### إعداد Agent أساسي لـ Google Drive + +```python +from crewai import Agent, Task, Crew + +# Create an agent with Google Drive capabilities +drive_agent = Agent( + role="File Manager", + goal="Manage files and folders in Google Drive efficiently", + backstory="An AI assistant specialized in document and file management.", + apps=['google_drive'] # All Google Drive actions will be available +) + +# Task to organize files +organize_files_task = Task( + description="List all files in the root directory and organize them into appropriate folders", + agent=drive_agent, + expected_output="Summary of files organized with folder structure" +) + +# Run the task +crew = Crew( + agents=[drive_agent], + tasks=[organize_files_task] +) + +crew.kickoff() +``` + +### تصفية أدوات Google Drive المحددة + +```python +from crewai import Agent, Task, Crew + +# Create agent with specific Google Drive actions only +file_manager_agent = Agent( + role="Document Manager", + goal="Upload and manage documents efficiently", + backstory="An AI assistant that focuses on document upload and organization.", + apps=[ + 'google_drive/upload_file', + 'google_drive/create_folder', + 'google_drive/share_file' + ] # Specific Google Drive actions +) + +# Task to upload and share documents +document_task = Task( + description="Upload the quarterly report and share it with the finance team", + agent=file_manager_agent, + expected_output="Document uploaded and sharing permissions configured" +) + +crew = Crew( + agents=[file_manager_agent], + tasks=[document_task] +) + +crew.kickoff() +``` + +### إدارة الملفات المتقدمة + +```python +from crewai import Agent, Task, Crew + +file_organizer = Agent( + role="File Organizer", + goal="Maintain organized file structure and manage permissions", + backstory="An experienced file manager who ensures proper organization and access control.", + apps=['google_drive'] +) + +# Complex task involving multiple Google Drive operations +organization_task = Task( + description=""" + 1. List all files in the shared folder + 2. Create folders for different document types (Reports, Presentations, Spreadsheets) + 3. Move files to appropriate folders based on their type + 4. Set appropriate sharing permissions for each folder + 5. Create a summary document of the organization changes + """, + agent=file_organizer, + expected_output="Files organized into categorized folders with proper permissions and summary report" +) + +crew = Crew( + agents=[file_organizer], + tasks=[organization_task] +) + +crew.kickoff() +``` diff --git a/docs/ar/enterprise/integrations/google_sheets.mdx b/docs/ar/enterprise/integrations/google_sheets.mdx new file mode 100644 index 000000000..5651ef83d --- /dev/null +++ b/docs/ar/enterprise/integrations/google_sheets.mdx @@ -0,0 +1,254 @@ +--- +title: تكامل Google Sheets +description: "مزامنة بيانات جداول البيانات مع تكامل Google Sheets لـ CrewAI." +icon: "google" +mode: "wide" +--- + +## نظرة عامة + +مكّن وكلاءك من إدارة بيانات جداول البيانات عبر Google Sheets. اقرأ الصفوف، وأنشئ إدخالات جديدة، وحدّث البيانات الموجودة، وبسّط سير عمل إدارة البيانات باستخدام الأتمتة المدعومة بالذكاء الاصطناعي. مثالي لتتبع البيانات وإعداد التقارير وإدارة البيانات التعاونية. + +## المتطلبات الأساسية + +قبل استخدام تكامل Google Sheets، تأكد من توفر ما يلي: + +- حساب [CrewAI AMP](https://app.crewai.com) مع اشتراك فعّال +- حساب Google مع إمكانية الوصول إلى Google Sheets +- ربط حساب Google الخاص بك عبر [صفحة التكاملات](https://app.crewai.com/crewai_plus/connectors) +- جداول بيانات بترويسات أعمدة مناسبة لعمليات البيانات + +## إعداد تكامل Google Sheets + +### 1. ربط حساب Google الخاص بك + +1. انتقل إلى [تكاملات CrewAI AMP](https://app.crewai.com/crewai_plus/connectors) +2. ابحث عن **Google Sheets** في قسم تكاملات المصادقة +3. انقر على **Connect** وأكمل عملية OAuth +4. امنح الصلاحيات اللازمة للوصول إلى جداول البيانات +5. انسخ رمز المؤسسة من [إعدادات التكامل](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. تثبيت الحزمة المطلوبة + +```bash +uv add crewai-tools +``` + +### 3. إعداد متغير البيئة + + + لاستخدام التكاملات مع `Agent(apps=[])`, يجب تعيين متغير البيئة + `CREWAI_PLATFORM_INTEGRATION_TOKEN` برمز المؤسسة الخاص بك. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +أو أضفه إلى ملف `.env`: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## الإجراءات المتاحة + + + + **الوصف:** استرجاع خصائص وبيانات جدول البيانات. + + **المعاملات:** + - `spreadsheetId` (string, مطلوب): معرّف جدول البيانات المراد استرجاعه. + - `ranges` (array, اختياري): النطاقات المراد استرجاعها من جدول البيانات. + - `includeGridData` (boolean, اختياري): true إذا كان يجب إرجاع بيانات الشبكة. الافتراضي: false + - `fields` (string, اختياري): الحقول المراد تضمينها في الاستجابة. + + + + + **الوصف:** إرجاع نطاق من القيم من جدول البيانات. + + **المعاملات:** + - `spreadsheetId` (string, مطلوب): معرّف جدول البيانات المراد استرجاع البيانات منه. + - `range` (string, مطلوب): ترميز A1 أو R1C1 للنطاق المراد استرجاع القيم منه. + - `valueRenderOption` (string, اختياري): كيفية تمثيل القيم في الإخراج. الخيارات: FORMATTED_VALUE, UNFORMATTED_VALUE, FORMULA. الافتراضي: FORMATTED_VALUE + - `dateTimeRenderOption` (string, اختياري): كيفية تمثيل التواريخ والأوقات في الإخراج. الخيارات: SERIAL_NUMBER, FORMATTED_STRING. الافتراضي: SERIAL_NUMBER + - `majorDimension` (string, اختياري): البُعد الرئيسي للنتائج. الخيارات: ROWS, COLUMNS. الافتراضي: ROWS + + + + + **الوصف:** تعيين القيم في نطاق من جدول البيانات. + + **المعاملات:** + - `spreadsheetId` (string, مطلوب): معرّف جدول البيانات المراد تحديثه. + - `range` (string, مطلوب): ترميز A1 للنطاق المراد تحديثه. + - `values` (array, مطلوب): البيانات المراد كتابتها. كل مصفوفة تمثل صفاً. + ```json + [ + ["Value1", "Value2", "Value3"], + ["Value4", "Value5", "Value6"] + ] + ``` + - `valueInputOption` (string, اختياري): كيفية تفسير بيانات الإدخال. الخيارات: RAW, USER_ENTERED. الافتراضي: USER_ENTERED + + + + + **الوصف:** إلحاق قيم بجدول البيانات. + + **المعاملات:** + - `spreadsheetId` (string, مطلوب): معرّف جدول البيانات المراد تحديثه. + - `range` (string, مطلوب): ترميز A1 لنطاق البحث عن جدول بيانات منطقي. + - `values` (array, مطلوب): البيانات المراد إلحاقها. كل مصفوفة تمثل صفاً. + ```json + [ + ["Value1", "Value2", "Value3"], + ["Value4", "Value5", "Value6"] + ] + ``` + - `valueInputOption` (string, اختياري): كيفية تفسير بيانات الإدخال. الخيارات: RAW, USER_ENTERED. الافتراضي: USER_ENTERED + - `insertDataOption` (string, اختياري): كيفية إدراج بيانات الإدخال. الخيارات: OVERWRITE, INSERT_ROWS. الافتراضي: INSERT_ROWS + + + + + **الوصف:** إنشاء جدول بيانات جديد. + + **المعاملات:** + - `title` (string, مطلوب): عنوان جدول البيانات الجديد. + - `sheets` (array, اختياري): الأوراق التي تشكل جزءاً من جدول البيانات. + ```json + [ + { + "properties": { + "title": "Sheet1" + } + } + ] + ``` + + + + +## أمثلة الاستخدام + +### إعداد Agent أساسي لـ Google Sheets + +```python +from crewai import Agent, Task, Crew + +# Create an agent with Google Sheets capabilities +sheets_agent = Agent( + role="Data Manager", + goal="Manage spreadsheet data and track information efficiently", + backstory="An AI assistant specialized in data management and spreadsheet operations.", + apps=['google_sheets'] +) + +# Task to add new data to a spreadsheet +data_entry_task = Task( + description="Add a new customer record to the customer database spreadsheet with name, email, and signup date", + agent=sheets_agent, + expected_output="New customer record added successfully to the spreadsheet" +) + +# Run the task +crew = Crew( + agents=[sheets_agent], + tasks=[data_entry_task] +) + +crew.kickoff() +``` + +### تصفية أدوات Google Sheets المحددة + +```python +from crewai import Agent, Task, Crew + +# Create agent with specific Google Sheets actions only +data_collector = Agent( + role="Data Collector", + goal="Collect and organize data in spreadsheets", + backstory="An AI assistant that focuses on data collection and organization.", + apps=[ + 'google_sheets/get_values', + 'google_sheets/update_values' + ] +) + +# Task to collect and organize data +data_collection = Task( + description="Retrieve current inventory data and add new product entries to the inventory spreadsheet", + agent=data_collector, + expected_output="Inventory data retrieved and new products added successfully" +) + +crew = Crew( + agents=[data_collector], + tasks=[data_collection] +) + +crew.kickoff() +``` + +### تحليل البيانات وإعداد التقارير + +```python +from crewai import Agent, Task, Crew + +data_analyst = Agent( + role="Data Analyst", + goal="Analyze spreadsheet data and generate insights", + backstory="An experienced data analyst who extracts insights from spreadsheet data.", + apps=['google_sheets'] +) + +# Task to analyze data and create reports +analysis_task = Task( + description=""" + 1. Retrieve all sales data from the current month's spreadsheet + 2. Analyze the data for trends and patterns + 3. Create a summary report in a new row with key metrics + """, + agent=data_analyst, + expected_output="Sales data analyzed and summary report created with key insights" +) + +crew = Crew( + agents=[data_analyst], + tasks=[analysis_task] +) + +crew.kickoff() +``` + +## استكشاف الأخطاء وإصلاحها + +### المشاكل الشائعة + +**أخطاء الصلاحيات** + +- تأكد من أن حساب Google الخاص بك لديه صلاحية التحرير على جداول البيانات المستهدفة +- تحقق من أن اتصال OAuth يتضمن النطاقات المطلوبة لـ Google Sheets API +- تأكد من مشاركة جداول البيانات مع الحساب المصادق عليه + +**مشاكل هيكل جدول البيانات** + +- تأكد من أن أوراق العمل تحتوي على ترويسات أعمدة مناسبة قبل إنشاء الصفوف أو تحديثها +- تحقق من صحة ترميز النطاق (صيغة A1) للخلايا المستهدفة +- تأكد من وجود معرّف جدول البيانات المحدد وإمكانية الوصول إليه + +**مشاكل نوع البيانات والصيغة** + +- تأكد من تطابق قيم البيانات مع الصيغة المتوقعة لكل عمود +- استخدم صيغ التاريخ المناسبة لأعمدة التاريخ (يُنصح بصيغة ISO) +- تحقق من صحة تنسيق القيم الرقمية لأعمدة الأرقام + +### الحصول على المساعدة + + + تواصل مع فريق الدعم للحصول على المساعدة في إعداد تكامل Google Sheets + أو استكشاف الأخطاء وإصلاحها. + diff --git a/docs/ar/enterprise/integrations/google_slides.mdx b/docs/ar/enterprise/integrations/google_slides.mdx new file mode 100644 index 000000000..77029f244 --- /dev/null +++ b/docs/ar/enterprise/integrations/google_slides.mdx @@ -0,0 +1,382 @@ +--- +title: تكامل Google Slides +description: "إنشاء العروض التقديمية وإدارتها مع تكامل Google Slides لـ CrewAI." +icon: "chart-bar" +mode: "wide" +--- + +## نظرة عامة + +مكّن وكلاءك من إنشاء وتحرير وإدارة عروض Google Slides التقديمية. أنشئ العروض التقديمية، وحدّث المحتوى، واستورد البيانات من Google Sheets، وأدر الصفحات والصور المصغرة، وبسّط سير عمل العروض التقديمية باستخدام الأتمتة المدعومة بالذكاء الاصطناعي. + +## المتطلبات الأساسية + +قبل استخدام تكامل Google Slides، تأكد من توفر ما يلي: + +- حساب [CrewAI AMP](https://app.crewai.com) مع اشتراك فعّال +- حساب Google مع إمكانية الوصول إلى Google Slides +- ربط حساب Google الخاص بك عبر [صفحة التكاملات](https://app.crewai.com/crewai_plus/connectors) + +## إعداد تكامل Google Slides + +### 1. ربط حساب Google الخاص بك + +1. انتقل إلى [تكاملات CrewAI AMP](https://app.crewai.com/crewai_plus/connectors) +2. ابحث عن **Google Slides** في قسم تكاملات المصادقة +3. انقر على **Connect** وأكمل عملية OAuth +4. امنح الصلاحيات اللازمة للوصول إلى العروض التقديمية وجداول البيانات وDrive +5. انسخ رمز المؤسسة من [إعدادات التكامل](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. تثبيت الحزمة المطلوبة + +```bash +uv add crewai-tools +``` + +### 3. إعداد متغير البيئة + + + لاستخدام التكاملات مع `Agent(apps=[])`, يجب تعيين متغير البيئة + `CREWAI_PLATFORM_INTEGRATION_TOKEN` برمز المؤسسة الخاص بك. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +أو أضفه إلى ملف `.env`: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## الإجراءات المتاحة + + + + **الوصف:** إنشاء عرض تقديمي فارغ بدون محتوى. + + **المعاملات:** + - `title` (string, مطلوب): عنوان العرض التقديمي. + + + + + **الوصف:** الحصول على بيانات وصفية خفيفة حول العرض التقديمي (العنوان، عدد الشرائح، معرّفات الشرائح). + + **المعاملات:** + - `presentationId` (string, مطلوب): معرّف العرض التقديمي المراد استرجاعه. + + + + + **الوصف:** استخراج جميع المحتوى النصي من العرض التقديمي. + + **المعاملات:** + - `presentationId` (string, مطلوب): معرّف العرض التقديمي. + + + + + **الوصف:** استرجاع عرض تقديمي بواسطة المعرّف. + + **المعاملات:** + - `presentationId` (string, مطلوب): معرّف العرض التقديمي المراد استرجاعه. + - `fields` (string, اختياري): الحقول المراد تضمينها في الاستجابة. + + + + + **الوصف:** تطبيق التحديثات أو إضافة المحتوى أو إزالته من العرض التقديمي. + + **المعاملات:** + - `presentationId` (string, مطلوب): معرّف العرض التقديمي المراد تحديثه. + - `requests` (array, مطلوب): قائمة بالتحديثات المراد تطبيقها. + ```json + [ + { + "insertText": { + "objectId": "slide_id", + "text": "Your text content here" + } + } + ] + ``` + - `writeControl` (object, اختياري): يوفر التحكم في كيفية تنفيذ طلبات الكتابة. + + + + + **الوصف:** استخراج المحتوى النصي من شريحة واحدة. + + **المعاملات:** + - `presentationId` (string, مطلوب): معرّف العرض التقديمي. + - `pageObjectId` (string, مطلوب): معرّف الشريحة/الصفحة. + + + + + **الوصف:** استرجاع صفحة محددة بواسطة معرّفها. + + **المعاملات:** + - `presentationId` (string, مطلوب): معرّف العرض التقديمي. + - `pageObjectId` (string, مطلوب): معرّف الصفحة المراد استرجاعها. + + + + + **الوصف:** إنشاء صورة مصغرة للصفحة. + + **المعاملات:** + - `presentationId` (string, مطلوب): معرّف العرض التقديمي. + - `pageObjectId` (string, مطلوب): معرّف الصفحة لإنشاء الصورة المصغرة. + + + + + **الوصف:** إضافة شريحة فارغة إضافية للعرض التقديمي. + + **المعاملات:** + - `presentationId` (string, مطلوب): معرّف العرض التقديمي. + - `insertionIndex` (integer, اختياري): مكان إدراج الشريحة (قائم على الصفر). إذا حُذف، تُضاف في النهاية. + + + + + **الوصف:** إنشاء شريحة بتخطيط محدد مسبقاً يحتوي على مناطق عناصر نائبة للعنوان والمحتوى وغيرها. + + **المعاملات:** + - `presentationId` (string, مطلوب): معرّف العرض التقديمي. + - `layout` (string, مطلوب): نوع التخطيط. أحد: `BLANK`, `TITLE`, `TITLE_AND_BODY`, `TITLE_AND_TWO_COLUMNS`, `TITLE_ONLY`, `SECTION_HEADER`, `ONE_COLUMN_TEXT`, `MAIN_POINT`, `BIG_NUMBER`. + - `insertionIndex` (integer, اختياري): مكان الإدراج (قائم على الصفر). حُذف للإضافة في النهاية. + + + + + **الوصف:** إنشاء مربع نص على شريحة مع محتوى. + + **المعاملات:** + - `presentationId` (string, مطلوب): معرّف العرض التقديمي. + - `slideId` (string, مطلوب): معرّف الشريحة لإضافة مربع النص إليها. + - `text` (string, مطلوب): المحتوى النصي لمربع النص. + - `x` (integer, اختياري): موضع X بوحدة EMU (914400 = 1 بوصة). الافتراضي: 914400. + - `y` (integer, اختياري): موضع Y بوحدة EMU. الافتراضي: 914400. + - `width` (integer, اختياري): العرض بوحدة EMU. الافتراضي: 7315200. + - `height` (integer, اختياري): الارتفاع بوحدة EMU. الافتراضي: 914400. + + + + + **الوصف:** إزالة شريحة من العرض التقديمي. + + **المعاملات:** + - `presentationId` (string, مطلوب): معرّف العرض التقديمي. + - `slideId` (string, مطلوب): معرّف الشريحة المراد حذفها. + + + + + **الوصف:** إنشاء نسخة من شريحة موجودة. + + **المعاملات:** + - `presentationId` (string, مطلوب): معرّف العرض التقديمي. + - `slideId` (string, مطلوب): معرّف الشريحة المراد تكرارها. + + + + + **الوصف:** إعادة ترتيب الشرائح بنقلها إلى موضع جديد. + + **المعاملات:** + - `presentationId` (string, مطلوب): معرّف العرض التقديمي. + - `slideIds` (array of strings, مطلوب): مصفوفة من معرّفات الشرائح المراد نقلها. + - `insertionIndex` (integer, مطلوب): الموضع المستهدف (قائم على الصفر). + + + + + **الوصف:** تضمين فيديو YouTube على شريحة. + + **المعاملات:** + - `presentationId` (string, مطلوب): معرّف العرض التقديمي. + - `slideId` (string, مطلوب): معرّف الشريحة لإضافة الفيديو إليها. + - `videoId` (string, مطلوب): معرّف فيديو YouTube (القيمة بعد v= في عنوان URL). + + + + + **الوصف:** تضمين فيديو من Google Drive على شريحة. + + **المعاملات:** + - `presentationId` (string, مطلوب): معرّف العرض التقديمي. + - `slideId` (string, مطلوب): معرّف الشريحة لإضافة الفيديو إليها. + - `fileId` (string, مطلوب): معرّف ملف Google Drive للفيديو. + + + + + **الوصف:** تعيين صورة خلفية لشريحة. + + **المعاملات:** + - `presentationId` (string, مطلوب): معرّف العرض التقديمي. + - `slideId` (string, مطلوب): معرّف الشريحة لتعيين الخلفية لها. + - `imageUrl` (string, مطلوب): عنوان URL المتاح للعموم للصورة المراد استخدامها كخلفية. + + + + + **الوصف:** إنشاء جدول فارغ على شريحة. + + **المعاملات:** + - `presentationId` (string, مطلوب): معرّف العرض التقديمي. + - `slideId` (string, مطلوب): معرّف الشريحة لإضافة الجدول إليها. + - `rows` (integer, مطلوب): عدد الصفوف في الجدول. + - `columns` (integer, مطلوب): عدد الأعمدة في الجدول. + + + + + **الوصف:** إنشاء جدول مع محتوى في إجراء واحد. + + **المعاملات:** + - `presentationId` (string, مطلوب): معرّف العرض التقديمي. + - `slideId` (string, مطلوب): معرّف الشريحة لإضافة الجدول إليها. + - `rows` (integer, مطلوب): عدد الصفوف في الجدول. + - `columns` (integer, مطلوب): عدد الأعمدة في الجدول. + - `content` (array, مطلوب): محتوى الجدول كمصفوفة ثنائية الأبعاد. مثال: [["Year", "Revenue"], ["2023", "$10M"]]. + + + + + **الوصف:** استيراد البيانات من Google Sheet إلى العرض التقديمي. + + **المعاملات:** + - `presentationId` (string, مطلوب): معرّف العرض التقديمي. + - `sheetId` (string, مطلوب): معرّف Google Sheet المراد الاستيراد منه. + - `dataRange` (string, مطلوب): نطاق البيانات المراد استيرادها من الورقة. + + + + + **الوصف:** رفع ملف إلى Google Drive المرتبط بالعرض التقديمي. + + **المعاملات:** + - `file` (string, مطلوب): بيانات الملف المراد رفعها. + - `presentationId` (string, مطلوب): معرّف العرض التقديمي لربط الملف المرفوع. + + + + + **الوصف:** ربط ملف في Google Drive بالعرض التقديمي. + + **المعاملات:** + - `presentationId` (string, مطلوب): معرّف العرض التقديمي. + - `fileId` (string, مطلوب): معرّف الملف المراد ربطه. + + + + + **الوصف:** عرض قائمة بجميع العروض التقديمية المتاحة للمستخدم. + + **المعاملات:** + - `pageSize` (integer, اختياري): عدد العروض التقديمية المراد إرجاعها لكل صفحة. + - `pageToken` (string, اختياري): رمز للترقيم. + + + + + **الوصف:** حذف عرض تقديمي بواسطة المعرّف. + + **المعاملات:** + - `presentationId` (string, مطلوب): معرّف العرض التقديمي المراد حذفه. + + + + +## أمثلة الاستخدام + +### إعداد Agent أساسي لـ Google Slides + +```python +from crewai import Agent, Task, Crew + +# Create an agent with Google Slides capabilities +slides_agent = Agent( + role="Presentation Manager", + goal="Create and manage presentations efficiently", + backstory="An AI assistant specialized in presentation creation and content management.", + apps=['google_slides'] # All Google Slides actions will be available +) + +# Task to create a presentation +create_presentation_task = Task( + description="Create a new presentation for the quarterly business review with key slides", + agent=slides_agent, + expected_output="Quarterly business review presentation created with structured content" +) + +# Run the task +crew = Crew( + agents=[slides_agent], + tasks=[create_presentation_task] +) + +crew.kickoff() +``` + +### إدارة محتوى العروض التقديمية + +```python +from crewai import Agent, Task, Crew + +content_manager = Agent( + role="Content Manager", + goal="Manage presentation content and updates", + backstory="An AI assistant that focuses on content creation and presentation updates.", + apps=[ + 'google_slides/create_blank_presentation', + 'google_slides/batch_update_presentation', + 'google_slides/get_presentation' + ] +) + +# Task to create and update presentations +content_task = Task( + description="Create a new presentation and add content slides with charts and text", + agent=content_manager, + expected_output="Presentation created with updated content and visual elements" +) + +crew = Crew( + agents=[content_manager], + tasks=[content_task] +) + +crew.kickoff() +``` + +## استكشاف الأخطاء وإصلاحها + +### المشاكل الشائعة + +**أخطاء الصلاحيات** + +- تأكد من أن حساب Google الخاص بك لديه الصلاحيات المناسبة لـ Google Slides +- تحقق من أن اتصال OAuth يتضمن النطاقات المطلوبة للعروض التقديمية وجداول البيانات وDrive + +**مشاكل معرّف العرض التقديمي** + +- تحقق من صحة معرّفات العروض التقديمية ووجودها +- تأكد من أن لديك صلاحيات الوصول للعروض التقديمية التي تحاول تعديلها + +**مشاكل تحديث المحتوى** + +- تأكد من صحة تنسيق طلبات التحديث الدفعي وفقاً لمواصفات Google Slides API +- تحقق من وجود معرّفات الكائنات للشرائح والعناصر في العرض التقديمي + +### الحصول على المساعدة + + + تواصل مع فريق الدعم للحصول على المساعدة في إعداد تكامل Google Slides + أو استكشاف الأخطاء وإصلاحها. + diff --git a/docs/ar/enterprise/integrations/hubspot.mdx b/docs/ar/enterprise/integrations/hubspot.mdx new file mode 100644 index 000000000..b328cebb7 --- /dev/null +++ b/docs/ar/enterprise/integrations/hubspot.mdx @@ -0,0 +1,360 @@ +--- +title: تكامل HubSpot +description: "إدارة الشركات وجهات الاتصال في HubSpot مع CrewAI." +icon: "briefcase" +mode: "wide" +--- + +## نظرة عامة + +مكّن وكلاءك من إدارة الشركات وجهات الاتصال داخل HubSpot. أنشئ سجلات جديدة وبسّط عمليات CRM باستخدام الأتمتة المدعومة بالذكاء الاصطناعي. + +## المتطلبات الأساسية + +قبل استخدام تكامل HubSpot، تأكد من توفر ما يلي: + +- حساب [CrewAI AMP](https://app.crewai.com) مع اشتراك فعّال. +- حساب HubSpot بالصلاحيات المناسبة. +- ربط حساب HubSpot الخاص بك عبر [صفحة التكاملات](https://app.crewai.com/crewai_plus/connectors). + +## إعداد تكامل HubSpot + +### 1. ربط حساب HubSpot الخاص بك + +1. انتقل إلى [تكاملات CrewAI AMP](https://app.crewai.com/crewai_plus/connectors). +2. ابحث عن **HubSpot** في قسم تكاملات المصادقة. +3. انقر على **Connect** وأكمل عملية OAuth. +4. امنح الصلاحيات اللازمة لإدارة الشركات وجهات الاتصال. +5. انسخ رمز المؤسسة من [إعدادات التكامل](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. تثبيت الحزمة المطلوبة + +```bash +uv add crewai-tools +``` + +### 3. إعداد متغير البيئة + + + لاستخدام التكاملات مع `Agent(apps=[])`, يجب تعيين متغير البيئة + `CREWAI_PLATFORM_INTEGRATION_TOKEN` برمز المؤسسة الخاص بك. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +أو أضفه إلى ملف `.env`: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## الإجراءات المتاحة + + + + **الوصف:** إنشاء سجل شركة جديد في HubSpot. + + **المعاملات:** + - `name` (string, مطلوب): اسم الشركة. + - `domain` (string, اختياري): اسم نطاق الشركة. + - `industry` (string, اختياري): القطاع. + - `phone` (string, اختياري): رقم الهاتف. + - `hubspot_owner_id` (string, اختياري): معرّف مالك الشركة. + - `type` (string, اختياري): نوع الشركة. القيم المتاحة: `PROSPECT`, `PARTNER`, `RESELLER`, `VENDOR`, `OTHER`. + - `city` (string, اختياري): المدينة. + - `state` (string, اختياري): الولاية/المنطقة. + - `zip` (string, اختياري): الرمز البريدي. + - `numberofemployees` (number, اختياري): عدد الموظفين. + - `annualrevenue` (number, اختياري): الإيرادات السنوية. + - `description` (string, اختياري): الوصف. + - `website` (string, اختياري): عنوان URL للموقع الإلكتروني. + + + + + **الوصف:** إنشاء سجل جهة اتصال جديد في HubSpot. + + **المعاملات:** + - `email` (string, مطلوب): عنوان البريد الإلكتروني لجهة الاتصال. + - `firstname` (string, اختياري): الاسم الأول. + - `lastname` (string, اختياري): اسم العائلة. + - `phone` (string, اختياري): رقم الهاتف. + - `hubspot_owner_id` (string, اختياري): مالك جهة الاتصال. + - `lifecyclestage` (string, اختياري): مرحلة دورة الحياة. القيم المتاحة: `subscriber`, `lead`, `marketingqualifiedlead`, `salesqualifiedlead`, `opportunity`, `customer`, `evangelist`, `other`. + - `company` (string, اختياري): اسم الشركة. + - `jobtitle` (string, اختياري): المسمى الوظيفي. + + + + + **الوصف:** إنشاء سجل صفقة جديد في HubSpot. + + **المعاملات:** + - `dealname` (string, مطلوب): اسم الصفقة. + - `amount` (number, اختياري): قيمة الصفقة. + - `dealstage` (string, اختياري): مرحلة مسار الصفقة. + - `pipeline` (string, اختياري): مسار المبيعات الذي تنتمي إليه الصفقة. + - `closedate` (string, اختياري): التاريخ المتوقع لإغلاق الصفقة. + - `hubspot_owner_id` (string, اختياري): مالك الصفقة. + - `dealtype` (string, اختياري): نوع الصفقة. القيم المتاحة: `newbusiness`, `existingbusiness`. + - `description` (string, اختياري): وصف الصفقة. + - `hs_priority` (string, اختياري): أولوية الصفقة. القيم المتاحة: `low`, `medium`, `high`. + + + + + **الوصف:** إنشاء تفاعل جديد (مثل ملاحظة، بريد إلكتروني، مكالمة، اجتماع، مهمة) في HubSpot. + + **المعاملات:** + - `engagementType` (string, مطلوب): نوع التفاعل. القيم المتاحة: `NOTE`, `EMAIL`, `CALL`, `MEETING`, `TASK`. + - `hubspot_owner_id` (string, اختياري): المستخدم المعيّن للنشاط. + - `hs_timestamp` (string, اختياري): تاريخ ووقت النشاط. + - `hs_note_body` (string, اختياري): نص الملاحظة. (يُستخدم لـ `NOTE`) + - `hs_task_subject` (string, اختياري): عنوان المهمة. (يُستخدم لـ `TASK`) + - `hs_meeting_title` (string, اختياري): عنوان الاجتماع. (يُستخدم لـ `MEETING`) + + + + + **الوصف:** تحديث سجل شركة موجود في HubSpot. + + **المعاملات:** + - `recordId` (string, مطلوب): معرّف الشركة المراد تحديثها. + - `name` (string, اختياري): اسم الشركة. + - `domain` (string, اختياري): اسم نطاق الشركة. + - `industry` (string, اختياري): القطاع. + - `phone` (string, اختياري): رقم الهاتف. + - `description` (string, اختياري): الوصف. + + + + + **الوصف:** تحديث سجل جهة اتصال موجود في HubSpot. + + **المعاملات:** + - `recordId` (string, مطلوب): معرّف جهة الاتصال المراد تحديثها. + - `firstname` (string, اختياري): الاسم الأول. + - `lastname` (string, اختياري): اسم العائلة. + - `email` (string, اختياري): عنوان البريد الإلكتروني. + - `phone` (string, اختياري): رقم الهاتف. + - `company` (string, اختياري): اسم الشركة. + - `jobtitle` (string, اختياري): المسمى الوظيفي. + + + + + **الوصف:** تحديث سجل صفقة موجود في HubSpot. + + **المعاملات:** + - `recordId` (string, مطلوب): معرّف الصفقة المراد تحديثها. + - `dealname` (string, اختياري): اسم الصفقة. + - `amount` (number, اختياري): قيمة الصفقة. + - `dealstage` (string, اختياري): مرحلة مسار الصفقة. + - `closedate` (string, اختياري): تاريخ الإغلاق المتوقع. + + + + + **الوصف:** الحصول على قائمة بسجلات الشركات من HubSpot. + + **المعاملات:** + - `paginationParameters` (object, اختياري): استخدم `pageCursor` لجلب الصفحات اللاحقة. + + + + + **الوصف:** الحصول على قائمة بسجلات جهات الاتصال من HubSpot. + + **المعاملات:** + - `paginationParameters` (object, اختياري): استخدم `pageCursor` لجلب الصفحات اللاحقة. + + + + + **الوصف:** الحصول على قائمة بسجلات الصفقات من HubSpot. + + **المعاملات:** + - `paginationParameters` (object, اختياري): استخدم `pageCursor` لجلب الصفحات اللاحقة. + + + + + **الوصف:** الحصول على سجل شركة واحد بواسطة معرّفه. + + **المعاملات:** + - `recordId` (string, مطلوب): معرّف الشركة المراد استرجاعها. + + + + + **الوصف:** الحصول على سجل جهة اتصال واحد بواسطة معرّفه. + + **المعاملات:** + - `recordId` (string, مطلوب): معرّف جهة الاتصال المراد استرجاعها. + + + + + **الوصف:** الحصول على سجل صفقة واحد بواسطة معرّفه. + + **المعاملات:** + - `recordId` (string, مطلوب): معرّف الصفقة المراد استرجاعها. + + + + + **الوصف:** البحث عن سجلات الشركات في HubSpot باستخدام صيغة فلتر. + + **المعاملات:** + - `filterFormula` (object, اختياري): فلتر بصيغة التعبير العادي المنفصل (OR لمجموعات AND). + - `paginationParameters` (object, اختياري): استخدم `pageCursor` لجلب الصفحات اللاحقة. + + + + + **الوصف:** البحث عن سجلات جهات الاتصال في HubSpot باستخدام صيغة فلتر. + + **المعاملات:** + - `filterFormula` (object, اختياري): فلتر بصيغة التعبير العادي المنفصل (OR لمجموعات AND). + - `paginationParameters` (object, اختياري): استخدم `pageCursor` لجلب الصفحات اللاحقة. + + + + + **الوصف:** البحث عن سجلات الصفقات في HubSpot باستخدام صيغة فلتر. + + **المعاملات:** + - `filterFormula` (object, اختياري): فلتر بصيغة التعبير العادي المنفصل (OR لمجموعات AND). + - `paginationParameters` (object, اختياري): استخدم `pageCursor` لجلب الصفحات اللاحقة. + + + + + **الوصف:** حذف سجل شركة بواسطة معرّفه. + + **المعاملات:** + - `recordId` (string, مطلوب): معرّف الشركة المراد حذفها. + + + + + **الوصف:** حذف سجل جهة اتصال بواسطة معرّفه. + + **المعاملات:** + - `recordId` (string, مطلوب): معرّف جهة الاتصال المراد حذفها. + + + + + **الوصف:** حذف سجل صفقة بواسطة معرّفه. + + **المعاملات:** + - `recordId` (string, مطلوب): معرّف الصفقة المراد حذفها. + + + + + **الوصف:** الحصول على المخطط المتوقع لنوع كائن وعملية معينة. + + **المعاملات:** + - `recordType` (string, مطلوب): معرّف نوع الكائن (مثال: 'companies'). + - `operation` (string, مطلوب): نوع العملية (مثال: 'CREATE_RECORD'). + + + + +## أمثلة الاستخدام + +### إعداد Agent أساسي لـ HubSpot + +```python +from crewai import Agent, Task, Crew + +# Create an agent with HubSpot capabilities +hubspot_agent = Agent( + role="CRM Manager", + goal="Manage company and contact records in HubSpot", + backstory="An AI assistant specialized in CRM management.", + apps=['hubspot'] # All HubSpot actions will be available +) + +# Task to create a new company +create_company_task = Task( + description="Create a new company in HubSpot with name 'Innovate Corp' and domain 'innovatecorp.com'.", + agent=hubspot_agent, + expected_output="Company created successfully with confirmation" +) + +# Run the task +crew = Crew( + agents=[hubspot_agent], + tasks=[create_company_task] +) + +crew.kickoff() +``` + +### تصفية أدوات HubSpot المحددة + +```python +from crewai import Agent, Task, Crew + +# Create agent with specific HubSpot actions only +contact_creator = Agent( + role="Contact Creator", + goal="Create new contacts in HubSpot", + backstory="An AI assistant that focuses on creating new contact entries in the CRM.", + apps=['hubspot/create_contact'] # Only contact creation action +) + +# Task to create a contact +create_contact = Task( + description="Create a new contact for 'John Doe' with email 'john.doe@example.com'.", + agent=contact_creator, + expected_output="Contact created successfully in HubSpot." +) + +crew = Crew( + agents=[contact_creator], + tasks=[create_contact] +) + +crew.kickoff() +``` + +### إدارة جهات الاتصال + +```python +from crewai import Agent, Task, Crew + +# Create agent with HubSpot contact management capabilities +crm_manager = Agent( + role="CRM Manager", + goal="Manage and organize HubSpot contacts efficiently.", + backstory="An experienced CRM manager who maintains an organized contact database.", + apps=['hubspot'] # All HubSpot actions including contact management +) + +# Task to manage contacts +contact_task = Task( + description="Create a new contact for 'Jane Smith' at 'Global Tech Inc.' with email 'jane.smith@globaltech.com'.", + agent=crm_manager, + expected_output="Contact database updated with the new contact." +) + +crew = Crew( + agents=[crm_manager], + tasks=[contact_task] +) + +crew.kickoff() +``` + +### الحصول على المساعدة + + + تواصل مع فريق الدعم للحصول على المساعدة في إعداد تكامل HubSpot أو + استكشاف الأخطاء وإصلاحها. + diff --git a/docs/ar/enterprise/integrations/jira.mdx b/docs/ar/enterprise/integrations/jira.mdx new file mode 100644 index 000000000..87fdea8a1 --- /dev/null +++ b/docs/ar/enterprise/integrations/jira.mdx @@ -0,0 +1,248 @@ +--- +title: تكامل Jira +description: "تتبع المشكلات وإدارة المشاريع مع تكامل Jira لـ CrewAI." +icon: "bug" +mode: "wide" +--- + +## نظرة عامة + +مكّن وكلاءك من إدارة المشكلات والمشاريع وسير العمل عبر Jira. أنشئ المشكلات وحدّثها، وتتبع تقدم المشاريع، وأدر التعيينات، وبسّط إدارة مشاريعك باستخدام الأتمتة المدعومة بالذكاء الاصطناعي. + +## المتطلبات الأساسية + +قبل استخدام تكامل Jira، تأكد من توفر ما يلي: + +- حساب [CrewAI AMP](https://app.crewai.com) مع اشتراك فعّال +- حساب Jira بصلاحيات المشروع المناسبة +- ربط حساب Jira الخاص بك عبر [صفحة التكاملات](https://app.crewai.com/crewai_plus/connectors) + +## إعداد تكامل Jira + +### 1. ربط حساب Jira الخاص بك + +1. انتقل إلى [تكاملات CrewAI AMP](https://app.crewai.com/crewai_plus/connectors) +2. ابحث عن **Jira** في قسم تكاملات المصادقة +3. انقر على **Connect** وأكمل عملية OAuth +4. امنح الصلاحيات اللازمة لإدارة المشكلات والمشاريع +5. انسخ رمز المؤسسة من [إعدادات التكامل](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. تثبيت الحزمة المطلوبة + +```bash +uv add crewai-tools +``` + +### 3. إعداد متغير البيئة + + + لاستخدام التكاملات مع `Agent(apps=[])`, يجب تعيين متغير البيئة + `CREWAI_PLATFORM_INTEGRATION_TOKEN` برمز المؤسسة الخاص بك. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +أو أضفه إلى ملف `.env`: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## الإجراءات المتاحة + + + + **الوصف:** إنشاء مشكلة في Jira. + + **المعاملات:** + - `summary` (string, مطلوب): الملخص - ملخص موجز من سطر واحد للمشكلة. (مثال: "The printer stopped working"). + - `project` (string, اختياري): المشروع - المشروع الذي تنتمي إليه المشكلة. + - `issueType` (string, اختياري): نوع المشكلة - الافتراضي هو Task. + - `jiraIssueStatus` (string, اختياري): الحالة - الافتراضي هو أول حالة في المشروع. + - `assignee` (string, اختياري): المكلّف - الافتراضي هو المستخدم المصادق عليه. + - `description` (string, اختياري): الوصف - وصف تفصيلي للمشكلة. + - `additionalFields` (string, اختياري): حقول إضافية - حدد أي حقول أخرى بصيغة JSON. + + + + + **الوصف:** تحديث مشكلة في Jira. + + **المعاملات:** + - `issueKey` (string, مطلوب): مفتاح المشكلة (مثال: "TEST-1234"). + - `summary` (string, اختياري): الملخص. + - `issueType` (string, اختياري): نوع المشكلة. + - `jiraIssueStatus` (string, اختياري): الحالة. + - `assignee` (string, اختياري): المكلّف. + - `description` (string, اختياري): الوصف. + - `additionalFields` (string, اختياري): حقول إضافية بصيغة JSON. + + + + + **الوصف:** الحصول على مشكلة بواسطة المفتاح في Jira. + + **المعاملات:** + - `issueKey` (string, مطلوب): مفتاح المشكلة (مثال: "TEST-1234"). + + + + + **الوصف:** البحث عن المشكلات في Jira باستخدام الفلاتر. + + **المعاملات:** + - `jqlQuery` (object, اختياري): فلتر بصيغة التعبير العادي المنفصل. + - `limit` (string, اختياري): حدود النتائج - الافتراضي 10. + + + + + **الوصف:** البحث عن المشكلات بواسطة JQL في Jira. + + **المعاملات:** + - `jqlQuery` (string, مطلوب): استعلام JQL (مثال: "project = PROJECT"). + - `paginationParameters` (object, اختياري): معاملات الترقيم. + + + + + **الوصف:** الحصول على المخطط المتوقع لنوع مشكلة. + + **المعاملات:** + - `issueTypeId` (string, مطلوب): معرّف نوع المشكلة. + - `projectKey` (string, مطلوب): مفتاح المشروع. + - `operation` (string, مطلوب): نوع العملية، مثال CREATE_ISSUE أو UPDATE_ISSUE. + + + + + **الوصف:** الحصول على المشاريع في Jira. + + **المعاملات:** + - `paginationParameters` (object, اختياري): معاملات الترقيم. + + + + + **الوصف:** الحصول على أنواع المشكلات بواسطة المشروع في Jira. + + **المعاملات:** + - `project` (string, مطلوب): مفتاح المشروع. + + + + + **الوصف:** الحصول على جميع أنواع المشكلات في Jira. + + **المعاملات:** لا توجد معاملات مطلوبة. + + + + + **الوصف:** الحصول على حالات المشكلات لمشروع معين. + + **المعاملات:** + - `project` (string, مطلوب): مفتاح المشروع. + + + + + **الوصف:** الحصول على المكلّفين لمشروع معين. + + **المعاملات:** + - `project` (string, مطلوب): مفتاح المشروع. + + + + +## أمثلة الاستخدام + +### إعداد Agent أساسي لـ Jira + +```python +from crewai import Agent, Task, Crew +from crewai import Agent, Task, Crew + +# Create an agent with Jira capabilities +jira_agent = Agent( + role="Issue Manager", + goal="Manage Jira issues and track project progress efficiently", + backstory="An AI assistant specialized in issue tracking and project management.", + apps=['jira'] # All Jira actions will be available +) + +# Task to create a bug report +create_bug_task = Task( + description="Create a bug report for the login functionality with high priority and assign it to the development team", + agent=jira_agent, + expected_output="Bug report created successfully with issue key" +) + +# Run the task +crew = Crew( + agents=[jira_agent], + tasks=[create_bug_task] +) + +crew.kickoff() +``` + +### تحليل المشاريع وإعداد التقارير + +```python +from crewai import Agent, Task, Crew + +project_analyst = Agent( + role="Project Analyst", + goal="Analyze project data and generate insights from Jira", + backstory="An experienced project analyst who extracts insights from project management data.", + apps=['jira'] +) + +# Task to analyze project status +analysis_task = Task( + description=""" + 1. Get all projects and their issue types + 2. Search for all open issues across projects + 3. Analyze issue distribution by status and assignee + 4. Create a summary report issue with findings + """, + agent=project_analyst, + expected_output="Project analysis completed with summary report created" +) + +crew = Crew( + agents=[project_analyst], + tasks=[analysis_task] +) + +crew.kickoff() +``` + +## استكشاف الأخطاء وإصلاحها + +### المشاكل الشائعة + +**أخطاء الصلاحيات** + +- تأكد من أن حساب Jira الخاص بك لديه الصلاحيات اللازمة للمشاريع المستهدفة +- تحقق من أن اتصال OAuth يتضمن النطاقات المطلوبة لـ Jira API + +**مفاتيح المشاريع أو المشكلات غير الصالحة** + +- تحقق جيداً من مفاتيح المشاريع ومفاتيح المشكلات للتأكد من صحة الصيغة (مثال: "PROJ-123") +- تأكد من وجود المشاريع وإمكانية الوصول إليها من حسابك + +**مشاكل استعلام JQL** + +- اختبر استعلامات JQL في بحث مشكلات Jira قبل استخدامها في استدعاءات API +- تأكد من صحة إملاء أسماء الحقول في JQL ووجودها في مثيل Jira الخاص بك + +### الحصول على المساعدة + + + تواصل مع فريق الدعم للحصول على المساعدة في إعداد تكامل Jira أو + استكشاف الأخطاء وإصلاحها. + diff --git a/docs/ar/enterprise/integrations/linear.mdx b/docs/ar/enterprise/integrations/linear.mdx new file mode 100644 index 000000000..c2eb34f84 --- /dev/null +++ b/docs/ar/enterprise/integrations/linear.mdx @@ -0,0 +1,261 @@ +--- +title: تكامل Linear +description: "إدارة المشاريع البرمجية وتتبع الأخطاء مع تكامل Linear لـ CrewAI." +icon: "list-check" +mode: "wide" +--- + +## نظرة عامة + +مكّن وكلاءك من إدارة المشكلات والمشاريع وسير عمل التطوير عبر Linear. أنشئ المشكلات وحدّثها، وأدر جداول المشاريع الزمنية، ونظّم الفرق، وبسّط عملية تطوير البرمجيات باستخدام الأتمتة المدعومة بالذكاء الاصطناعي. + +## المتطلبات الأساسية + +قبل استخدام تكامل Linear، تأكد من توفر ما يلي: + +- حساب [CrewAI AMP](https://app.crewai.com) مع اشتراك فعّال +- حساب Linear بصلاحيات مساحة العمل المناسبة +- ربط حساب Linear الخاص بك عبر [صفحة التكاملات](https://app.crewai.com/crewai_plus/connectors) + +## إعداد تكامل Linear + +### 1. ربط حساب Linear الخاص بك + +1. انتقل إلى [تكاملات CrewAI AMP](https://app.crewai.com/crewai_plus/connectors) +2. ابحث عن **Linear** في قسم تكاملات المصادقة +3. انقر على **Connect** وأكمل عملية OAuth +4. امنح الصلاحيات اللازمة لإدارة المشكلات والمشاريع +5. انسخ رمز المؤسسة من [إعدادات التكامل](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. تثبيت الحزمة المطلوبة + +```bash +uv add crewai-tools +``` + +### 3. إعداد متغير البيئة + + + لاستخدام التكاملات مع `Agent(apps=[])`, يجب تعيين متغير البيئة + `CREWAI_PLATFORM_INTEGRATION_TOKEN` برمز المؤسسة الخاص بك. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +أو أضفه إلى ملف `.env`: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## الإجراءات المتاحة + + + + **الوصف:** إنشاء مشكلة جديدة في Linear. + + **المعاملات:** + - `teamId` (string, مطلوب): معرّف الفريق للمشكلة الجديدة. + - `title` (string, مطلوب): العنوان. + - `description` (string, اختياري): الوصف. + - `statusId` (string, اختياري): الحالة. + - `priority` (string, اختياري): الأولوية كعدد صحيح. + - `dueDate` (string, اختياري): تاريخ الاستحقاق بصيغة ISO 8601. + - `cycleId` (string, اختياري): معرّف الدورة المرتبطة. + - `additionalFields` (object, اختياري): حقول إضافية. + + + + + **الوصف:** تحديث مشكلة في Linear. + + **المعاملات:** + - `issueId` (string, مطلوب): معرّف المشكلة المراد تحديثها. + - `title` (string, اختياري): العنوان. + - `description` (string, اختياري): الوصف. + - `statusId` (string, اختياري): الحالة. + - `priority` (string, اختياري): الأولوية. + - `dueDate` (string, اختياري): تاريخ الاستحقاق. + + + + + **الوصف:** الحصول على مشكلة بواسطة المعرّف في Linear. + + **المعاملات:** + - `issueId` (string, مطلوب): معرّف المشكلة المراد جلبها. + + + + + **الوصف:** البحث عن المشكلات في Linear. + + **المعاملات:** + - `queryTerm` (string, مطلوب): مصطلح البحث. + - `issueFilterFormula` (object, اختياري): فلتر بصيغة التعبير العادي المنفصل. + + + + + **الوصف:** حذف مشكلة في Linear. + + **المعاملات:** + - `issueId` (string, مطلوب): معرّف المشكلة المراد حذفها. + + + + + **الوصف:** أرشفة مشكلة في Linear. + + **المعاملات:** + - `issueId` (string, مطلوب): معرّف المشكلة المراد أرشفتها. + + + + + **الوصف:** إنشاء مشكلة فرعية في Linear. + + **المعاملات:** + - `parentId` (string, مطلوب): معرّف المشكلة الأصلية. + - `teamId` (string, مطلوب): معرّف الفريق. + - `title` (string, مطلوب): العنوان. + - `description` (string, اختياري): الوصف. + + + + + **الوصف:** إنشاء مشروع جديد في Linear. + + **المعاملات:** + - `teamIds` (object, مطلوب): معرّف (معرّفات) الفريق المرتبطة بالمشروع. + - `projectName` (string, مطلوب): اسم المشروع. + - `description` (string, اختياري): وصف المشروع. + + + + + **الوصف:** تحديث مشروع في Linear. + + **المعاملات:** + - `projectId` (string, مطلوب): معرّف المشروع المراد تحديثه. + - `projectName` (string, اختياري): اسم المشروع. + - `description` (string, اختياري): وصف المشروع. + + + + + **الوصف:** الحصول على مشروع بواسطة المعرّف في Linear. + + **المعاملات:** + - `projectId` (string, مطلوب): معرّف المشروع المراد جلبه. + + + + + **الوصف:** حذف مشروع في Linear. + + **المعاملات:** + - `projectId` (string, مطلوب): معرّف المشروع المراد حذفه. + + + + + **الوصف:** البحث عن الفرق في Linear. + + **المعاملات:** + - `teamFilterFormula` (object, اختياري): فلتر بصيغة التعبير العادي المنفصل. + + + + +## أمثلة الاستخدام + +### إعداد Agent أساسي لـ Linear + +```python +from crewai import Agent, Task, Crew +from crewai import Agent, Task, Crew + +# Create an agent with Linear capabilities +linear_agent = Agent( + role="Development Manager", + goal="Manage Linear issues and track development progress efficiently", + backstory="An AI assistant specialized in software development project management.", + apps=['linear'] # All Linear actions will be available +) + +# Task to create a bug report +create_bug_task = Task( + description="Create a high-priority bug report for the authentication system and assign it to the backend team", + agent=linear_agent, + expected_output="Bug report created successfully with issue ID" +) + +# Run the task +crew = Crew( + agents=[linear_agent], + tasks=[create_bug_task] +) + +crew.kickoff() +``` + +### إدارة المشاريع والفرق + +```python +from crewai import Agent, Task, Crew + +project_coordinator = Agent( + role="Project Coordinator", + goal="Coordinate projects and teams in Linear efficiently", + backstory="An experienced project coordinator who manages development cycles and team workflows.", + apps=['linear'] +) + +# Task to coordinate project setup +project_coordination = Task( + description=""" + 1. Search for engineering teams in Linear + 2. Create a new project for Q2 feature development + 3. Associate the project with relevant teams + 4. Create initial project milestones as issues + """, + agent=project_coordinator, + expected_output="Q2 project created with teams assigned and initial milestones established" +) + +crew = Crew( + agents=[project_coordinator], + tasks=[project_coordination] +) + +crew.kickoff() +``` + +## استكشاف الأخطاء وإصلاحها + +### المشاكل الشائعة + +**أخطاء الصلاحيات** + +- تأكد من أن حساب Linear الخاص بك لديه الصلاحيات اللازمة لمساحة العمل المستهدفة +- تحقق من أن اتصال OAuth يتضمن النطاقات المطلوبة لـ Linear API + +**معرّفات ومراجع غير صالحة** + +- تحقق جيداً من معرّفات الفرق والمشكلات والمشاريع للتأكد من صحة صيغة UUID +- تأكد من وجود الكيانات المشار إليها وإمكانية الوصول إليها + +**مشاكل التاريخ والوقت** + +- استخدم صيغة ISO 8601 لتواريخ الاستحقاق والطوابع الزمنية +- تأكد من معالجة المناطق الزمنية بشكل صحيح + +### الحصول على المساعدة + + + تواصل مع فريق الدعم للحصول على المساعدة في إعداد تكامل Linear أو + استكشاف الأخطاء وإصلاحها. + diff --git a/docs/ar/enterprise/integrations/microsoft_excel.mdx b/docs/ar/enterprise/integrations/microsoft_excel.mdx new file mode 100644 index 000000000..0ce049695 --- /dev/null +++ b/docs/ar/enterprise/integrations/microsoft_excel.mdx @@ -0,0 +1,269 @@ +--- +title: تكامل Microsoft Excel +description: "إدارة المصنفات والبيانات مع تكامل Microsoft Excel لـ CrewAI." +icon: "table" +mode: "wide" +--- + +## نظرة عامة + +مكّن وكلاءك من إنشاء وإدارة مصنفات Excel وأوراق العمل والجداول والرسوم البيانية في OneDrive أو SharePoint. تعامل مع نطاقات البيانات، وأنشئ المرئيات، وأدر الجداول، وبسّط سير عمل جداول البيانات باستخدام الأتمتة المدعومة بالذكاء الاصطناعي. + +## المتطلبات الأساسية + +قبل استخدام تكامل Microsoft Excel، تأكد من توفر ما يلي: + +- حساب [CrewAI AMP](https://app.crewai.com) مع اشتراك فعّال +- حساب Microsoft 365 مع إمكانية الوصول إلى Excel وOneDrive/SharePoint +- ربط حساب Microsoft الخاص بك عبر [صفحة التكاملات](https://app.crewai.com/crewai_plus/connectors) + +## إعداد تكامل Microsoft Excel + +### 1. ربط حساب Microsoft الخاص بك + +1. انتقل إلى [تكاملات CrewAI AMP](https://app.crewai.com/crewai_plus/connectors) +2. ابحث عن **Microsoft Excel** في قسم تكاملات المصادقة +3. انقر على **Connect** وأكمل عملية OAuth +4. امنح الصلاحيات اللازمة للوصول إلى الملفات ومصنفات Excel +5. انسخ رمز المؤسسة من [إعدادات التكامل](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. تثبيت الحزمة المطلوبة + +```bash +uv add crewai-tools +``` + +### 3. إعداد متغير البيئة + + + لاستخدام التكاملات مع `Agent(apps=[])`, يجب تعيين متغير البيئة + `CREWAI_PLATFORM_INTEGRATION_TOKEN` برمز المؤسسة الخاص بك. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +أو أضفه إلى ملف `.env`: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## الإجراءات المتاحة + + + + **الوصف:** إنشاء مصنف Excel جديد في OneDrive أو SharePoint. + + **المعاملات:** + - `file_path` (string, مطلوب): المسار حيث يتم إنشاء المصنف (مثال: 'MyWorkbook.xlsx') + - `worksheets` (array, اختياري): أوراق العمل الأولية المراد إنشاؤها + + + + + **الوصف:** الحصول على جميع مصنفات Excel من OneDrive أو SharePoint. + + **المعاملات:** + - `select` (string, اختياري): اختيار خصائص محددة للإرجاع + - `filter` (string, اختياري): تصفية النتائج باستخدام صيغة OData + - `top` (integer, اختياري): عدد العناصر المراد إرجاعها. الحد الأدنى: 1، الحد الأقصى: 999 + + + + + **الوصف:** الحصول على جميع أوراق العمل في مصنف Excel. + + **المعاملات:** + - `file_id` (string, مطلوب): معرّف ملف Excel + + + + + **الوصف:** إنشاء ورقة عمل جديدة في مصنف Excel. + + **المعاملات:** + - `file_id` (string, مطلوب): معرّف ملف Excel + - `name` (string, مطلوب): اسم ورقة العمل الجديدة + + + + + **الوصف:** الحصول على البيانات من نطاق محدد في ورقة عمل Excel. + + **المعاملات:** + - `file_id` (string, مطلوب): معرّف ملف Excel + - `worksheet_name` (string, مطلوب): اسم ورقة العمل + - `range` (string, مطلوب): عنوان النطاق (مثال: 'A1:C10') + + + + + **الوصف:** تحديث البيانات في نطاق محدد في ورقة عمل Excel. + + **المعاملات:** + - `file_id` (string, مطلوب): معرّف ملف Excel + - `worksheet_name` (string, مطلوب): اسم ورقة العمل + - `range` (string, مطلوب): عنوان النطاق (مثال: 'A1:C10') + - `values` (array, مطلوب): مصفوفة ثنائية الأبعاد من القيم لتعيينها في النطاق + + + + + **الوصف:** إنشاء جدول في ورقة عمل Excel. + + **المعاملات:** + - `file_id` (string, مطلوب): معرّف ملف Excel + - `worksheet_name` (string, مطلوب): اسم ورقة العمل + - `range` (string, مطلوب): النطاق للجدول (مثال: 'A1:D10') + - `has_headers` (boolean, اختياري): ما إذا كان الصف الأول يحتوي على ترويسات. الافتراضي: true + + + + + **الوصف:** إضافة صف جديد إلى جدول Excel. + + **المعاملات:** + - `file_id` (string, مطلوب): معرّف ملف Excel + - `worksheet_name` (string, مطلوب): اسم ورقة العمل + - `table_name` (string, مطلوب): اسم الجدول + - `values` (array, مطلوب): مصفوفة من القيم للصف الجديد + + + + + **الوصف:** إنشاء رسم بياني في ورقة عمل Excel. + + **المعاملات:** + - `file_id` (string, مطلوب): معرّف ملف Excel + - `worksheet_name` (string, مطلوب): اسم ورقة العمل + - `chart_type` (string, مطلوب): نوع الرسم البياني (مثال: 'ColumnClustered', 'Line', 'Pie') + - `source_data` (string, مطلوب): نطاق البيانات للرسم البياني (مثال: 'A1:B10') + - `series_by` (string, اختياري): كيفية تفسير البيانات ('Auto', 'Columns', 'Rows'). الافتراضي: Auto + + + + + **الوصف:** الحصول على قيمة خلية واحدة في ورقة عمل Excel. + + **المعاملات:** + - `file_id` (string, مطلوب): معرّف ملف Excel + - `worksheet_name` (string, مطلوب): اسم ورقة العمل + - `row` (integer, مطلوب): رقم الصف (قائم على الصفر) + - `column` (integer, مطلوب): رقم العمود (قائم على الصفر) + + + + + **الوصف:** الحصول على النطاق المستخدم لورقة عمل Excel (يحتوي على جميع البيانات). + + **المعاملات:** + - `file_id` (string, مطلوب): معرّف ملف Excel + - `worksheet_name` (string, مطلوب): اسم ورقة العمل + + + + + **الوصف:** الحصول على جميع الجداول في ورقة عمل Excel. + + **المعاملات:** + - `file_id` (string, مطلوب): معرّف ملف Excel + - `worksheet_name` (string, مطلوب): اسم ورقة العمل + + + + + **الوصف:** الحصول على البيانات من جدول محدد في ورقة عمل Excel. + + **المعاملات:** + - `file_id` (string, مطلوب): معرّف ملف Excel + - `worksheet_name` (string, مطلوب): اسم ورقة العمل + - `table_name` (string, مطلوب): اسم الجدول + + + + + **الوصف:** حذف ورقة عمل من مصنف Excel. + + **المعاملات:** + - `file_id` (string, مطلوب): معرّف ملف Excel + - `worksheet_name` (string, مطلوب): اسم ورقة العمل المراد حذفها + + + + + **الوصف:** حذف جدول من ورقة عمل Excel. + + **المعاملات:** + - `file_id` (string, مطلوب): معرّف ملف Excel + - `worksheet_name` (string, مطلوب): اسم ورقة العمل + - `table_name` (string, مطلوب): اسم الجدول المراد حذفه + + + + + **الوصف:** الحصول على جميع النطاقات المسماة في مصنف Excel. + + **المعاملات:** + - `file_id` (string, مطلوب): معرّف ملف Excel + + + + +## أمثلة الاستخدام + +### إعداد Agent أساسي لـ Excel + +```python +from crewai import Agent, Task, Crew + +# Create an agent with Excel capabilities +excel_agent = Agent( + role="Excel Data Manager", + goal="Manage Excel workbooks and data efficiently", + backstory="An AI assistant specialized in Excel data management and analysis.", + apps=['microsoft_excel'] # All Excel actions will be available +) + +# Task to create and populate a workbook +data_management_task = Task( + description="Create a new sales report workbook with data analysis and charts", + agent=excel_agent, + expected_output="Excel workbook created with sales data, analysis, and visualizations" +) + +# Run the task +crew = Crew( + agents=[excel_agent], + tasks=[data_management_task] +) + +crew.kickoff() +``` + +## استكشاف الأخطاء وإصلاحها + +### المشاكل الشائعة + +**أخطاء الصلاحيات** + +- تأكد من أن حساب Microsoft الخاص بك لديه الصلاحيات المناسبة لـ Excel وOneDrive/SharePoint +- تحقق من أن اتصال OAuth يتضمن النطاقات المطلوبة (Files.Read.All, Files.ReadWrite.All) + +**مشاكل النطاق وورقة العمل** + +- تحقق من وجود أسماء أوراق العمل في المصنف المحدد +- تأكد من صحة تنسيق عناوين النطاقات (مثال: 'A1:C10') + +**مشاكل الرسوم البيانية** + +- تحقق من دعم أنواع الرسوم البيانية (ColumnClustered, Line, Pie، إلخ.) +- تأكد من أن نطاقات بيانات المصدر تحتوي على بيانات مناسبة لنوع الرسم البياني + +### الحصول على المساعدة + + + تواصل مع فريق الدعم للحصول على المساعدة في إعداد تكامل Microsoft Excel + أو استكشاف الأخطاء وإصلاحها. + diff --git a/docs/ar/enterprise/integrations/microsoft_onedrive.mdx b/docs/ar/enterprise/integrations/microsoft_onedrive.mdx new file mode 100644 index 000000000..7ce92c1c0 --- /dev/null +++ b/docs/ar/enterprise/integrations/microsoft_onedrive.mdx @@ -0,0 +1,218 @@ +--- +title: تكامل Microsoft OneDrive +description: "إدارة الملفات والمجلدات مع تكامل Microsoft OneDrive لـ CrewAI." +icon: "cloud" +mode: "wide" +--- + +## نظرة عامة + +مكّن وكلاءك من رفع وتحميل وإدارة الملفات والمجلدات في Microsoft OneDrive. أتمت عمليات الملفات، ونظّم المحتوى، وأنشئ روابط المشاركة، وبسّط سير عمل التخزين السحابي باستخدام الأتمتة المدعومة بالذكاء الاصطناعي. + +## المتطلبات الأساسية + +قبل استخدام تكامل Microsoft OneDrive، تأكد من توفر ما يلي: + +- حساب [CrewAI AMP](https://app.crewai.com) مع اشتراك فعّال +- حساب Microsoft مع إمكانية الوصول إلى OneDrive +- ربط حساب Microsoft الخاص بك عبر [صفحة التكاملات](https://app.crewai.com/crewai_plus/connectors) + +## إعداد تكامل Microsoft OneDrive + +### 1. ربط حساب Microsoft الخاص بك + +1. انتقل إلى [تكاملات CrewAI AMP](https://app.crewai.com/crewai_plus/connectors) +2. ابحث عن **Microsoft OneDrive** في قسم تكاملات المصادقة +3. انقر على **Connect** وأكمل عملية OAuth +4. امنح الصلاحيات اللازمة للوصول إلى الملفات +5. انسخ رمز المؤسسة من [إعدادات التكامل](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. تثبيت الحزمة المطلوبة + +```bash +uv add crewai-tools +``` + +### 3. إعداد متغير البيئة + + + لاستخدام التكاملات مع `Agent(apps=[])`, يجب تعيين متغير البيئة + `CREWAI_PLATFORM_INTEGRATION_TOKEN` برمز المؤسسة الخاص بك. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +أو أضفه إلى ملف `.env`: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## الإجراءات المتاحة + + + + **الوصف:** عرض الملفات والمجلدات في OneDrive. + + **المعاملات:** + - `top` (integer, اختياري): عدد العناصر المراد استرجاعها (الحد الأقصى 1000). الافتراضي: `50`. + - `orderby` (string, اختياري): الترتيب حسب حقل (مثال: "name asc", "lastModifiedDateTime desc"). الافتراضي: "name asc". + - `filter` (string, اختياري): تعبير فلتر OData. + + + + + **الوصف:** الحصول على معلومات حول ملف أو مجلد محدد. + + **المعاملات:** + - `item_id` (string, مطلوب): معرّف الملف أو المجلد. + + + + + **الوصف:** تحميل ملف من OneDrive. + + **المعاملات:** + - `item_id` (string, مطلوب): معرّف الملف المراد تحميله. + + + + + **الوصف:** رفع ملف إلى OneDrive. + + **المعاملات:** + - `file_name` (string, مطلوب): اسم الملف المراد رفعه. + - `content` (string, مطلوب): محتوى الملف بترميز Base64. + + + + + **الوصف:** إنشاء مجلد جديد في OneDrive. + + **المعاملات:** + - `folder_name` (string, مطلوب): اسم المجلد المراد إنشاؤه. + + + + + **الوصف:** حذف ملف أو مجلد من OneDrive. + + **المعاملات:** + - `item_id` (string, مطلوب): معرّف الملف أو المجلد المراد حذفه. + + + + + **الوصف:** نسخ ملف أو مجلد في OneDrive. + + **المعاملات:** + - `item_id` (string, مطلوب): معرّف الملف أو المجلد المراد نسخه. + - `parent_id` (string, اختياري): معرّف مجلد الوجهة (اختياري، الافتراضي هو الجذر). + - `new_name` (string, اختياري): الاسم الجديد للعنصر المنسوخ (اختياري). + + + + + **الوصف:** نقل ملف أو مجلد في OneDrive. + + **المعاملات:** + - `item_id` (string, مطلوب): معرّف الملف أو المجلد المراد نقله. + - `parent_id` (string, مطلوب): معرّف مجلد الوجهة. + - `new_name` (string, اختياري): الاسم الجديد للعنصر (اختياري). + + + + + **الوصف:** البحث عن الملفات والمجلدات في OneDrive. + + **المعاملات:** + - `query` (string, مطلوب): سلسلة استعلام البحث. + - `top` (integer, اختياري): عدد النتائج المراد إرجاعها (الحد الأقصى 1000). الافتراضي: `50`. + + + + + **الوصف:** إنشاء رابط مشاركة لملف أو مجلد. + + **المعاملات:** + - `item_id` (string, مطلوب): معرّف الملف أو المجلد المراد مشاركته. + - `type` (string, اختياري): نوع رابط المشاركة. القيم: `view`, `edit`, `embed`. الافتراضي: `view`. + - `scope` (string, اختياري): نطاق رابط المشاركة. القيم: `anonymous`, `organization`. الافتراضي: `anonymous`. + + + + + **الوصف:** الحصول على الملفات التي تم الوصول إليها مؤخراً من OneDrive. + + **المعاملات:** + - `top` (integer, اختياري): عدد العناصر المراد استرجاعها (الحد الأقصى 200). الافتراضي: `25`. + + + + + **الوصف:** الحصول على الملفات والمجلدات المشاركة مع المستخدم. + + **المعاملات:** + - `top` (integer, اختياري): عدد العناصر المراد استرجاعها (الحد الأقصى 200). الافتراضي: `50`. + + + + +## أمثلة الاستخدام + +### إعداد Agent أساسي لـ Microsoft OneDrive + +```python +from crewai import Agent, Task, Crew + +# Create an agent with Microsoft OneDrive capabilities +onedrive_agent = Agent( + role="File Manager", + goal="Manage files and folders in OneDrive efficiently", + backstory="An AI assistant specialized in Microsoft OneDrive file operations and organization.", + apps=['microsoft_onedrive'] # All OneDrive actions will be available +) + +# Task to list files and create a folder +organize_files_task = Task( + description="List all files in my OneDrive root directory and create a new folder called 'Project Documents'.", + agent=onedrive_agent, + expected_output="List of files displayed and new folder 'Project Documents' created." +) + +# Run the task +crew = Crew( + agents=[onedrive_agent], + tasks=[organize_files_task] +) + +crew.kickoff() +``` + +## استكشاف الأخطاء وإصلاحها + +### المشاكل الشائعة + +**أخطاء المصادقة** + +- تأكد من أن حساب Microsoft الخاص بك لديه الصلاحيات اللازمة للوصول إلى الملفات (مثال: `Files.Read`, `Files.ReadWrite`). +- تحقق من أن اتصال OAuth يتضمن جميع النطاقات المطلوبة. + +**مشاكل رفع الملفات** + +- تأكد من توفير `file_name` و`content` لعمليات رفع الملفات. +- يجب أن يكون المحتوى بترميز Base64 للملفات الثنائية. + +**عمليات الملفات (النسخ/النقل)** + +- لـ `move_item`، تأكد من توفير كل من `item_id` و`parent_id`. +- تحقق من وجود مجلدات الوجهة وإمكانية الوصول إليها. + +### الحصول على المساعدة + + + تواصل مع فريق الدعم للحصول على المساعدة في إعداد تكامل Microsoft OneDrive + أو استكشاف الأخطاء وإصلاحها. + diff --git a/docs/ar/enterprise/integrations/microsoft_outlook.mdx b/docs/ar/enterprise/integrations/microsoft_outlook.mdx new file mode 100644 index 000000000..f1a6cd99e --- /dev/null +++ b/docs/ar/enterprise/integrations/microsoft_outlook.mdx @@ -0,0 +1,227 @@ +--- +title: تكامل Microsoft Outlook +description: "إدارة البريد الإلكتروني والتقويم وجهات الاتصال مع تكامل Microsoft Outlook لـ CrewAI." +icon: "envelope" +mode: "wide" +--- + +## نظرة عامة + +مكّن وكلاءك من الوصول إلى رسائل Outlook الإلكترونية وأحداث التقويم وجهات الاتصال وإدارتها. أرسل رسائل البريد الإلكتروني، واسترجع الرسائل، وأدر أحداث التقويم، ونظّم جهات الاتصال باستخدام الأتمتة المدعومة بالذكاء الاصطناعي. + +## المتطلبات الأساسية + +قبل استخدام تكامل Microsoft Outlook، تأكد من توفر ما يلي: + +- حساب [CrewAI AMP](https://app.crewai.com) مع اشتراك فعّال +- حساب Microsoft مع إمكانية الوصول إلى Outlook +- ربط حساب Microsoft الخاص بك عبر [صفحة التكاملات](https://app.crewai.com/crewai_plus/connectors) + +## إعداد تكامل Microsoft Outlook + +### 1. ربط حساب Microsoft الخاص بك + +1. انتقل إلى [تكاملات CrewAI AMP](https://app.crewai.com/crewai_plus/connectors) +2. ابحث عن **Microsoft Outlook** في قسم تكاملات المصادقة +3. انقر على **Connect** وأكمل عملية OAuth +4. امنح الصلاحيات اللازمة للوصول إلى البريد والتقويم وجهات الاتصال +5. انسخ رمز المؤسسة من [إعدادات التكامل](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. تثبيت الحزمة المطلوبة + +```bash +uv add crewai-tools +``` + +### 3. إعداد متغير البيئة + + + لاستخدام التكاملات مع `Agent(apps=[])`, يجب تعيين متغير البيئة + `CREWAI_PLATFORM_INTEGRATION_TOKEN` برمز المؤسسة الخاص بك. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +أو أضفه إلى ملف `.env`: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## الإجراءات المتاحة + + + + **الوصف:** الحصول على رسائل البريد الإلكتروني من صندوق بريد المستخدم. + + **المعاملات:** + - `top` (integer, اختياري): عدد الرسائل (الحد الأقصى 1000). الافتراضي: `10`. + - `filter` (string, اختياري): تعبير فلتر OData (مثال: "isRead eq false"). + - `search` (string, اختياري): سلسلة استعلام البحث. + - `orderby` (string, اختياري): الترتيب (مثال: "receivedDateTime desc"). الافتراضي: "receivedDateTime desc". + + + + + **الوصف:** إرسال رسالة بريد إلكتروني. + + **المعاملات:** + - `to_recipients` (array, مطلوب): مصفوفة عناوين المستلمين. + - `subject` (string, مطلوب): موضوع البريد الإلكتروني. + - `body` (string, مطلوب): محتوى البريد الإلكتروني. + - `body_type` (string, اختياري): نوع المحتوى. القيم: `Text`, `HTML`. الافتراضي: `HTML`. + - `importance` (string, اختياري): مستوى الأهمية. القيم: `low`, `normal`, `high`. الافتراضي: `normal`. + - `cc_recipients` (array, اختياري): مصفوفة عناوين النسخة الكربونية. + + + + + **الوصف:** الحصول على أحداث التقويم من تقويم المستخدم. + + **المعاملات:** + - `top` (integer, اختياري): عدد الأحداث (الحد الأقصى 1000). الافتراضي: `10`. + - `filter` (string, اختياري): تعبير فلتر OData. + - `orderby` (string, اختياري): الترتيب. الافتراضي: "start/dateTime asc". + + + + + **الوصف:** إنشاء حدث تقويم جديد. + + **المعاملات:** + - `subject` (string, مطلوب): موضوع/عنوان الحدث. + - `start_datetime` (string, مطلوب): وقت البداية بصيغة ISO 8601. + - `end_datetime` (string, مطلوب): وقت النهاية بصيغة ISO 8601. + - `timezone` (string, اختياري): المنطقة الزمنية. الافتراضي: `UTC`. + - `location` (string, اختياري): موقع الحدث. + - `attendees` (array, اختياري): مصفوفة عناوين الحضور. + + + + + **الوصف:** الحصول على جهات الاتصال من دفتر عناوين المستخدم. + + **المعاملات:** + - `top` (integer, اختياري): عدد جهات الاتصال (الحد الأقصى 1000). الافتراضي: `10`. + - `filter` (string, اختياري): تعبير فلتر OData. + + + + + **الوصف:** إنشاء جهة اتصال جديدة في دفتر عناوين المستخدم. + + **المعاملات:** + - `displayName` (string, مطلوب): اسم العرض لجهة الاتصال. + - `givenName` (string, اختياري): الاسم الأول. + - `surname` (string, اختياري): اسم العائلة. + - `emailAddresses` (array, اختياري): مصفوفة عناوين البريد الإلكتروني. + - `jobTitle` (string, اختياري): المسمى الوظيفي. + - `companyName` (string, اختياري): اسم الشركة. + + + + + **الوصف:** الرد على رسالة بريد إلكتروني. + + **المعاملات:** + - `message_id` (string, مطلوب): المعرّف الفريد للرسالة المراد الرد عليها. + - `comment` (string, مطلوب): محتوى الرد. + + + + + **الوصف:** إعادة توجيه رسالة بريد إلكتروني. + + **المعاملات:** + - `message_id` (string, مطلوب): المعرّف الفريد للرسالة المراد إعادة توجيهها. + - `to_recipients` (array, مطلوب): مصفوفة عناوين المستلمين. + - `comment` (string, اختياري): رسالة اختيارية لتضمينها فوق المحتوى المُعاد توجيهه. + + + + + **الوصف:** حذف رسالة بريد إلكتروني. + + **المعاملات:** + - `message_id` (string, مطلوب): المعرّف الفريد للرسالة المراد حذفها. + + + + + **الوصف:** تحديث حدث تقويم موجود. + + **المعاملات:** + - `event_id` (string, مطلوب): المعرّف الفريد للحدث. + - `subject` (string, اختياري): الموضوع/العنوان الجديد. + - `start_time` (string, اختياري): وقت البداية الجديد بصيغة ISO 8601. + - `location` (string, اختياري): الموقع الجديد. + + + + + **الوصف:** حذف حدث تقويم. + + **المعاملات:** + - `event_id` (string, مطلوب): المعرّف الفريد للحدث المراد حذفه. + + + + +## أمثلة الاستخدام + +### إعداد Agent أساسي لـ Microsoft Outlook + +```python +from crewai import Agent, Task, Crew + +# Create an agent with Microsoft Outlook capabilities +outlook_agent = Agent( + role="Email Assistant", + goal="Manage emails, calendar events, and contacts efficiently", + backstory="An AI assistant specialized in Microsoft Outlook operations and communication management.", + apps=['microsoft_outlook'] # All Outlook actions will be available +) + +# Task to send an email +send_email_task = Task( + description="Send an email to 'colleague@example.com' with subject 'Project Update' and body 'Hi, here is the latest project update. Best regards.'", + agent=outlook_agent, + expected_output="Email sent successfully to colleague@example.com" +) + +# Run the task +crew = Crew( + agents=[outlook_agent], + tasks=[send_email_task] +) + +crew.kickoff() +``` + +## استكشاف الأخطاء وإصلاحها + +### المشاكل الشائعة + +**أخطاء المصادقة** + +- تأكد من أن حساب Microsoft الخاص بك لديه الصلاحيات اللازمة للوصول إلى البريد والتقويم وجهات الاتصال. +- النطاقات المطلوبة تشمل: `Mail.Read`, `Mail.Send`, `Calendars.ReadWrite`, `Contacts.ReadWrite`. + +**مشاكل إرسال البريد الإلكتروني** + +- تأكد من توفير `to_recipients` و`subject` و`body` لـ `send_email`. +- تحقق من صحة صيغة عناوين البريد الإلكتروني. + +**إنشاء أحداث التقويم** + +- تأكد من توفير `subject` و`start_datetime` و`end_datetime`. +- استخدم صيغة ISO 8601 المناسبة لحقول التاريخ والوقت. + +### الحصول على المساعدة + + + تواصل مع فريق الدعم للحصول على المساعدة في إعداد تكامل Microsoft Outlook + أو استكشاف الأخطاء وإصلاحها. + diff --git a/docs/ar/enterprise/integrations/microsoft_sharepoint.mdx b/docs/ar/enterprise/integrations/microsoft_sharepoint.mdx new file mode 100644 index 000000000..56b88708d --- /dev/null +++ b/docs/ar/enterprise/integrations/microsoft_sharepoint.mdx @@ -0,0 +1,270 @@ +--- +title: تكامل Microsoft SharePoint +description: "إدارة المواقع والقوائم والمستندات مع تكامل Microsoft SharePoint لـ CrewAI." +icon: "folder-tree" +mode: "wide" +--- + +## نظرة عامة + +مكّن وكلاءك من الوصول إلى مواقع SharePoint والقوائم ومكتبات المستندات وإدارتها. استرجع معلومات المواقع، وأدر عناصر القوائم، وارفع الملفات ونظّمها، وبسّط سير عمل SharePoint باستخدام الأتمتة المدعومة بالذكاء الاصطناعي. + +## المتطلبات الأساسية + +قبل استخدام تكامل Microsoft SharePoint، تأكد من توفر ما يلي: + +- حساب [CrewAI AMP](https://app.crewai.com) مع اشتراك فعّال +- حساب Microsoft 365 مع إمكانية الوصول إلى SharePoint +- ربط حساب Microsoft الخاص بك عبر [صفحة التكاملات](https://app.crewai.com/crewai_plus/connectors) + +## إعداد تكامل Microsoft SharePoint + +### 1. ربط حساب Microsoft الخاص بك + +1. انتقل إلى [تكاملات CrewAI AMP](https://app.crewai.com/crewai_plus/connectors) +2. ابحث عن **Microsoft SharePoint** في قسم تكاملات المصادقة +3. انقر على **Connect** وأكمل عملية OAuth +4. امنح الصلاحيات اللازمة للوصول إلى مواقع SharePoint ومحتوياتها +5. انسخ رمز المؤسسة من [إعدادات التكامل](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. تثبيت الحزمة المطلوبة + +```bash +uv add crewai-tools +``` + +### 3. إعداد متغير البيئة + + + لاستخدام التكاملات مع `Agent(apps=[])`, يجب تعيين متغير البيئة + `CREWAI_PLATFORM_INTEGRATION_TOKEN` برمز المؤسسة الخاص بك. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +أو أضفه إلى ملف `.env`: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## الإجراءات المتاحة + + + + **الوصف:** الحصول على جميع مواقع SharePoint التي يمكن للمستخدم الوصول إليها. + + **المعاملات:** + - `search` (string, اختياري): استعلام بحث لتصفية المواقع + - `top` (integer, اختياري): عدد العناصر المراد إرجاعها. الحد الأدنى: 1، الحد الأقصى: 999 + + + + + **الوصف:** الحصول على معلومات حول موقع SharePoint محدد. + + **المعاملات:** + - `site_id` (string, مطلوب): معرّف موقع SharePoint + + + + + **الوصف:** عرض جميع مكتبات المستندات (drives) في موقع SharePoint. + + **المعاملات:** + - `site_id` (string, مطلوب): معرّف موقع SharePoint الكامل + + + + + **الوصف:** الحصول على جميع القوائم في موقع SharePoint. + + **المعاملات:** + - `site_id` (string, مطلوب): معرّف موقع SharePoint + + + + + **الوصف:** الحصول على عناصر من قائمة SharePoint. + + **المعاملات:** + - `site_id` (string, مطلوب): معرّف موقع SharePoint + - `list_id` (string, مطلوب): معرّف القائمة + - `expand` (string, اختياري): توسيع البيانات المرتبطة (مثال: 'fields') + + + + + **الوصف:** إنشاء عنصر جديد في قائمة SharePoint. + + **المعاملات:** + - `site_id` (string, مطلوب): معرّف موقع SharePoint + - `list_id` (string, مطلوب): معرّف القائمة + - `fields` (object, مطلوب): قيم الحقول للعنصر الجديد + + + + + **الوصف:** تحديث عنصر في قائمة SharePoint. + + **المعاملات:** + - `site_id` (string, مطلوب): معرّف موقع SharePoint + - `list_id` (string, مطلوب): معرّف القائمة + - `item_id` (string, مطلوب): معرّف العنصر المراد تحديثه + - `fields` (object, مطلوب): قيم الحقول المراد تحديثها + + + + + **الوصف:** حذف عنصر من قائمة SharePoint. + + **المعاملات:** + - `site_id` (string, مطلوب): معرّف موقع SharePoint + - `list_id` (string, مطلوب): معرّف القائمة + - `item_id` (string, مطلوب): معرّف العنصر المراد حذفه + + + + + **الوصف:** رفع ملف إلى مكتبة مستندات SharePoint. + + **المعاملات:** + - `site_id` (string, مطلوب): معرّف موقع SharePoint + - `file_path` (string, مطلوب): المسار حيث يتم رفع الملف + - `content` (string, مطلوب): محتوى الملف المراد رفعه + + + + + **الوصف:** استرجاع الملفات والمجلدات من مكتبة مستندات SharePoint. + + **المعاملات:** + - `site_id` (string, مطلوب): معرّف موقع SharePoint الكامل + - `drive_id` (string, مطلوب): معرّف مكتبة المستندات + - `folder_id` (string, اختياري): معرّف المجلد. الافتراضي: 'root' + - `top` (integer, اختياري): الحد الأقصى لعدد العناصر. الافتراضي: 50 + + + + + **الوصف:** البحث عن الملفات والمجلدات في مكتبة مستندات SharePoint بالكلمات المفتاحية. + + **المعاملات:** + - `site_id` (string, مطلوب): معرّف موقع SharePoint الكامل + - `drive_id` (string, مطلوب): معرّف مكتبة المستندات + - `query` (string, مطلوب): كلمات البحث المفتاحية + + + + + **الوصف:** حذف ملف أو مجلد من مكتبة مستندات SharePoint. + + **المعاملات:** + - `site_id` (string, مطلوب): معرّف موقع SharePoint الكامل + - `drive_id` (string, مطلوب): معرّف مكتبة المستندات + - `item_id` (string, مطلوب): المعرّف الفريد للملف أو المجلد المراد حذفه + + + + + **الوصف:** إنشاء مجلد جديد في مكتبة مستندات SharePoint. + + **المعاملات:** + - `site_id` (string, مطلوب): معرّف موقع SharePoint الكامل + - `drive_id` (string, مطلوب): معرّف مكتبة المستندات + - `folder_name` (string, مطلوب): اسم المجلد الجديد + - `parent_id` (string, اختياري): معرّف المجلد الأصلي. الافتراضي: 'root' + + + + + **الوصف:** تحميل محتوى ملف خام من مكتبة مستندات SharePoint. + + **المعاملات:** + - `site_id` (string, مطلوب): معرّف موقع SharePoint الكامل + - `drive_id` (string, مطلوب): معرّف مكتبة المستندات + - `item_id` (string, مطلوب): المعرّف الفريد للملف المراد تحميله + + + + + **الوصف:** نسخ ملف أو مجلد إلى موقع جديد داخل SharePoint. + + **المعاملات:** + - `site_id` (string, مطلوب): معرّف موقع SharePoint الكامل + - `drive_id` (string, مطلوب): معرّف مكتبة المستندات + - `item_id` (string, مطلوب): المعرّف الفريد للملف أو المجلد المراد نسخه + - `destination_folder_id` (string, مطلوب): معرّف مجلد الوجهة + + + + + **الوصف:** نقل ملف أو مجلد إلى موقع جديد داخل SharePoint. + + **المعاملات:** + - `site_id` (string, مطلوب): معرّف موقع SharePoint الكامل + - `drive_id` (string, مطلوب): معرّف مكتبة المستندات + - `item_id` (string, مطلوب): المعرّف الفريد للملف أو المجلد المراد نقله + - `destination_folder_id` (string, مطلوب): معرّف مجلد الوجهة + + + + +## أمثلة الاستخدام + +### إعداد Agent أساسي لـ SharePoint + +```python +from crewai import Agent, Task, Crew + +# Create an agent with SharePoint capabilities +sharepoint_agent = Agent( + role="SharePoint Manager", + goal="Manage SharePoint sites, lists, and documents efficiently", + backstory="An AI assistant specialized in SharePoint content management and collaboration.", + apps=['microsoft_sharepoint'] # All SharePoint actions will be available +) + +# Task to organize SharePoint content +content_organization_task = Task( + description="List all accessible SharePoint sites and organize content by department", + agent=sharepoint_agent, + expected_output="SharePoint sites listed and content organized by department" +) + +# Run the task +crew = Crew( + agents=[sharepoint_agent], + tasks=[content_organization_task] +) + +crew.kickoff() +``` + +## استكشاف الأخطاء وإصلاحها + +### المشاكل الشائعة + +**أخطاء الصلاحيات** + +- تأكد من أن حساب Microsoft الخاص بك لديه الصلاحيات المناسبة لمواقع SharePoint +- تحقق من أن اتصال OAuth يتضمن النطاقات المطلوبة (Sites.Read.All, Sites.ReadWrite.All) + +**مشاكل معرّفات المواقع والقوائم** + +- تحقق من صحة معرّفات المواقع والقوائم وصيغتها الصحيحة +- استخدم إجراءات get_sites وget_site_lists لاكتشاف المعرّفات الصالحة + +**مشاكل الحقول والمخطط** + +- تأكد من تطابق أسماء الحقول تماماً مع مخطط قائمة SharePoint +- تحقق من تضمين الحقول المطلوبة عند إنشاء أو تحديث عناصر القوائم + +### الحصول على المساعدة + + + تواصل مع فريق الدعم للحصول على المساعدة في إعداد تكامل Microsoft SharePoint + أو استكشاف الأخطاء وإصلاحها. + diff --git a/docs/ar/enterprise/integrations/microsoft_teams.mdx b/docs/ar/enterprise/integrations/microsoft_teams.mdx new file mode 100644 index 000000000..9714fa580 --- /dev/null +++ b/docs/ar/enterprise/integrations/microsoft_teams.mdx @@ -0,0 +1,205 @@ +--- +title: تكامل Microsoft Teams +description: "التعاون الجماعي والتواصل مع تكامل Microsoft Teams لـ CrewAI." +icon: "users" +mode: "wide" +--- + +## نظرة عامة + +مكّن وكلاءك من الوصول إلى بيانات Teams وإرسال الرسائل وإنشاء الاجتماعات وإدارة القنوات. أتمت التواصل الجماعي، وجدوِل الاجتماعات، واسترجع الرسائل، وبسّط سير عمل التعاون باستخدام الأتمتة المدعومة بالذكاء الاصطناعي. + +## المتطلبات الأساسية + +قبل استخدام تكامل Microsoft Teams، تأكد من توفر ما يلي: + +- حساب [CrewAI AMP](https://app.crewai.com) مع اشتراك فعّال +- حساب Microsoft مع إمكانية الوصول إلى Teams +- ربط حساب Microsoft الخاص بك عبر [صفحة التكاملات](https://app.crewai.com/crewai_plus/connectors) + +## إعداد تكامل Microsoft Teams + +### 1. ربط حساب Microsoft الخاص بك + +1. انتقل إلى [تكاملات CrewAI AMP](https://app.crewai.com/crewai_plus/connectors) +2. ابحث عن **Microsoft Teams** في قسم تكاملات المصادقة +3. انقر على **Connect** وأكمل عملية OAuth +4. امنح الصلاحيات اللازمة للوصول إلى Teams +5. انسخ رمز المؤسسة من [إعدادات التكامل](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. تثبيت الحزمة المطلوبة + +```bash +uv add crewai-tools +``` + +### 3. إعداد متغير البيئة + + + لاستخدام التكاملات مع `Agent(apps=[])`, يجب تعيين متغير البيئة + `CREWAI_PLATFORM_INTEGRATION_TOKEN` برمز المؤسسة الخاص بك. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +أو أضفه إلى ملف `.env`: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## الإجراءات المتاحة + + + + **الوصف:** الحصول على جميع الفرق التي ينتمي إليها المستخدم. + + **المعاملات:** + - لا توجد معاملات مطلوبة. + + + + + **الوصف:** الحصول على القنوات في فريق محدد. + + **المعاملات:** + - `team_id` (string, مطلوب): معرّف الفريق. + + + + + **الوصف:** إرسال رسالة إلى قناة Teams. + + **المعاملات:** + - `team_id` (string, مطلوب): معرّف الفريق. + - `channel_id` (string, مطلوب): معرّف القناة. + - `message` (string, مطلوب): محتوى الرسالة. + - `content_type` (string, اختياري): نوع المحتوى (html أو text). الافتراضي: `text`. + + + + + **الوصف:** الحصول على الرسائل من قناة Teams. + + **المعاملات:** + - `team_id` (string, مطلوب): معرّف الفريق. + - `channel_id` (string, مطلوب): معرّف القناة. + - `top` (integer, اختياري): عدد الرسائل (الحد الأقصى 50). الافتراضي: `20`. + + + + + **الوصف:** إنشاء اجتماع Teams. + + **المعاملات:** + - `subject` (string, مطلوب): موضوع/عنوان الاجتماع. + - `startDateTime` (string, مطلوب): وقت بداية الاجتماع (صيغة ISO 8601 مع المنطقة الزمنية). + - `endDateTime` (string, مطلوب): وقت نهاية الاجتماع (صيغة ISO 8601 مع المنطقة الزمنية). + + + + + **الوصف:** الحصول على أعضاء فريق محدد. + + **المعاملات:** + - `team_id` (string, مطلوب): المعرّف الفريد للفريق. + - `top` (integer, اختياري): الحد الأقصى لعدد الأعضاء (1-999). الافتراضي: `100`. + + + + + **الوصف:** إنشاء قناة جديدة في فريق. + + **المعاملات:** + - `team_id` (string, مطلوب): المعرّف الفريد للفريق. + - `display_name` (string, مطلوب): اسم القناة. الحد الأقصى 50 حرفاً. + - `description` (string, اختياري): وصف اختياري يشرح غرض القناة. + - `membership_type` (string, اختياري): ظهور القناة. القيم: `standard`, `private`. الافتراضي: `standard`. + + + + + **الوصف:** الرد على رسالة في قناة Teams. + + **المعاملات:** + - `team_id` (string, مطلوب): المعرّف الفريد للفريق. + - `channel_id` (string, مطلوب): المعرّف الفريد للقناة. + - `message_id` (string, مطلوب): المعرّف الفريد للرسالة المراد الرد عليها. + - `message` (string, مطلوب): محتوى الرد. + - `content_type` (string, اختياري): صيغة المحتوى. القيم: `html`, `text`. الافتراضي: `text`. + + + + + **الوصف:** تحديث اجتماع عبر الإنترنت موجود. + + **المعاملات:** + - `meeting_id` (string, مطلوب): المعرّف الفريد للاجتماع. + - `subject` (string, اختياري): عنوان الاجتماع الجديد. + - `startDateTime` (string, اختياري): وقت البداية الجديد بصيغة ISO 8601. + - `endDateTime` (string, اختياري): وقت النهاية الجديد بصيغة ISO 8601. + + + + + **الوصف:** حذف اجتماع عبر الإنترنت. + + **المعاملات:** + - `meeting_id` (string, مطلوب): المعرّف الفريد للاجتماع المراد حذفه. + + + + +## أمثلة الاستخدام + +### إعداد Agent أساسي لـ Microsoft Teams + +```python +from crewai import Agent, Task, Crew + +# Create an agent with Microsoft Teams capabilities +teams_agent = Agent( + role="Teams Coordinator", + goal="Manage Teams communication and meetings efficiently", + backstory="An AI assistant specialized in Microsoft Teams operations and team collaboration.", + apps=['microsoft_teams'] # All Teams actions will be available +) + +# Task to list teams and channels +explore_teams_task = Task( + description="List all teams I'm a member of and then get the channels for the first team.", + agent=teams_agent, + expected_output="List of teams and channels displayed." +) + +# Run the task +crew = Crew( + agents=[teams_agent], + tasks=[explore_teams_task] +) + +crew.kickoff() +``` + +## استكشاف الأخطاء وإصلاحها + +### المشاكل الشائعة + +**أخطاء المصادقة** + +- تأكد من أن حساب Microsoft الخاص بك لديه الصلاحيات اللازمة للوصول إلى Teams. +- النطاقات المطلوبة تشمل: `Team.ReadBasic.All`, `Channel.ReadBasic.All`, `ChannelMessage.Send`, `OnlineMeetings.ReadWrite`. + +**إنشاء الاجتماعات** + +- تأكد من توفير `subject` و`startDateTime` و`endDateTime`. +- استخدم صيغة ISO 8601 مع المنطقة الزمنية لحقول التاريخ والوقت. + +### الحصول على المساعدة + + + تواصل مع فريق الدعم للحصول على المساعدة في إعداد تكامل Microsoft Teams + أو استكشاف الأخطاء وإصلاحها. + diff --git a/docs/ar/enterprise/integrations/microsoft_word.mdx b/docs/ar/enterprise/integrations/microsoft_word.mdx new file mode 100644 index 000000000..32ab4eb5b --- /dev/null +++ b/docs/ar/enterprise/integrations/microsoft_word.mdx @@ -0,0 +1,168 @@ +--- +title: تكامل Microsoft Word +description: "إنشاء المستندات وإدارتها مع تكامل Microsoft Word لـ CrewAI." +icon: "file-word" +mode: "wide" +--- + +## نظرة عامة + +مكّن وكلاءك من إنشاء وقراءة وإدارة مستندات Word والملفات النصية في OneDrive أو SharePoint. أتمت إنشاء المستندات، واسترجع المحتوى، وأدر خصائص المستندات، وبسّط سير عمل المستندات باستخدام الأتمتة المدعومة بالذكاء الاصطناعي. + +## المتطلبات الأساسية + +قبل استخدام تكامل Microsoft Word، تأكد من توفر ما يلي: + +- حساب [CrewAI AMP](https://app.crewai.com) مع اشتراك فعّال +- حساب Microsoft مع إمكانية الوصول إلى Word وOneDrive/SharePoint +- ربط حساب Microsoft الخاص بك عبر [صفحة التكاملات](https://app.crewai.com/crewai_plus/connectors) + +## إعداد تكامل Microsoft Word + +### 1. ربط حساب Microsoft الخاص بك + +1. انتقل إلى [تكاملات CrewAI AMP](https://app.crewai.com/crewai_plus/connectors) +2. ابحث عن **Microsoft Word** في قسم تكاملات المصادقة +3. انقر على **Connect** وأكمل عملية OAuth +4. امنح الصلاحيات اللازمة للوصول إلى الملفات +5. انسخ رمز المؤسسة من [إعدادات التكامل](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. تثبيت الحزمة المطلوبة + +```bash +uv add crewai-tools +``` + +### 3. إعداد متغير البيئة + + + لاستخدام التكاملات مع `Agent(apps=[])`, يجب تعيين متغير البيئة + `CREWAI_PLATFORM_INTEGRATION_TOKEN` برمز المؤسسة الخاص بك. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +أو أضفه إلى ملف `.env`: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## الإجراءات المتاحة + + + + **الوصف:** الحصول على جميع مستندات Word من OneDrive أو SharePoint. + + **المعاملات:** + - `top` (integer, اختياري): عدد العناصر المراد إرجاعها (الحد الأدنى 1، الحد الأقصى 999). + - `filter` (string, اختياري): تصفية النتائج باستخدام صيغة OData. + + + + + **الوصف:** إنشاء مستند نصي (.txt) مع محتوى. يُنصح به لإنشاء المحتوى برمجياً. + + **المعاملات:** + - `file_name` (string, مطلوب): اسم المستند النصي (يجب أن ينتهي بـ .txt). + - `content` (string, اختياري): المحتوى النصي للمستند. + + + + + **الوصف:** الحصول على محتوى مستند (يعمل بشكل أفضل مع الملفات النصية). + + **المعاملات:** + - `file_id` (string, مطلوب): معرّف المستند. + + + + + **الوصف:** الحصول على خصائص وبيانات وصفية لمستند. + + **المعاملات:** + - `file_id` (string, مطلوب): معرّف المستند. + + + + + **الوصف:** حذف مستند. + + **المعاملات:** + - `file_id` (string, مطلوب): معرّف المستند المراد حذفه. + + + + + **الوصف:** نسخ مستند إلى موقع جديد في OneDrive. + + **المعاملات:** + - `file_id` (string, مطلوب): معرّف المستند المراد نسخه + - `name` (string, اختياري): الاسم الجديد للمستند المنسوخ + - `parent_id` (string, اختياري): معرّف مجلد الوجهة (الافتراضي هو الجذر) + + + + + **الوصف:** نقل مستند إلى موقع جديد في OneDrive. + + **المعاملات:** + - `file_id` (string, مطلوب): معرّف المستند المراد نقله + - `parent_id` (string, مطلوب): معرّف مجلد الوجهة + - `name` (string, اختياري): الاسم الجديد للمستند المنقول + + + + +## أمثلة الاستخدام + +### إعداد Agent أساسي لـ Microsoft Word + +```python +from crewai import Agent, Task, Crew + +# Create an agent with Microsoft Word capabilities +word_agent = Agent( + role="Document Manager", + goal="Manage Word documents and text files efficiently", + backstory="An AI assistant specialized in Microsoft Word document operations and content management.", + apps=['microsoft_word'] # All Word actions will be available +) + +# Task to create a new text document +create_doc_task = Task( + description="Create a new text document named 'meeting_notes.txt' with content 'Meeting Notes from January 2024: Key discussion points and action items.'", + agent=word_agent, + expected_output="New text document 'meeting_notes.txt' created successfully." +) + +# Run the task +crew = Crew( + agents=[word_agent], + tasks=[create_doc_task] +) + +crew.kickoff() +``` + +## استكشاف الأخطاء وإصلاحها + +### المشاكل الشائعة + +**أخطاء المصادقة** + +- تأكد من أن حساب Microsoft الخاص بك لديه الصلاحيات اللازمة للوصول إلى الملفات (`Files.Read.All`, `Files.ReadWrite.All`). + +**مشاكل إنشاء الملفات** + +- عند إنشاء مستندات نصية، تأكد من أن `file_name` ينتهي بامتداد `.txt`. +- تحقق من أن لديك صلاحيات الكتابة للموقع المستهدف. + +### الحصول على المساعدة + + + تواصل مع فريق الدعم للحصول على المساعدة في إعداد تكامل Microsoft Word + أو استكشاف الأخطاء وإصلاحها. + diff --git a/docs/ar/enterprise/integrations/notion.mdx b/docs/ar/enterprise/integrations/notion.mdx new file mode 100644 index 000000000..ef7849009 --- /dev/null +++ b/docs/ar/enterprise/integrations/notion.mdx @@ -0,0 +1,149 @@ +--- +title: تكامل Notion +description: "إدارة المستخدمين والتعليقات مع تكامل Notion لـ CrewAI." +icon: "book" +mode: "wide" +--- + +## نظرة عامة + +مكّن وكلاءك من إدارة المستخدمين وإنشاء التعليقات عبر Notion. يمكنك الوصول إلى معلومات مستخدمي مساحة العمل وإنشاء تعليقات على الصفحات والمناقشات، مما يبسّط سير عمل التعاون باستخدام الأتمتة المدعومة بالذكاء الاصطناعي. + +## المتطلبات الأساسية + +قبل استخدام تكامل Notion، تأكد من توفر ما يلي: + +- حساب [CrewAI AMP](https://app.crewai.com) مع اشتراك فعّال +- حساب Notion بصلاحيات مساحة العمل المناسبة +- ربط حساب Notion الخاص بك عبر [صفحة التكاملات](https://app.crewai.com/crewai_plus/connectors) + +## إعداد تكامل Notion + +### 1. ربط حساب Notion الخاص بك + +1. انتقل إلى [تكاملات CrewAI AMP](https://app.crewai.com/crewai_plus/connectors) +2. ابحث عن **Notion** في قسم تكاملات المصادقة +3. انقر على **Connect** وأكمل عملية OAuth +4. امنح الصلاحيات اللازمة للوصول إلى المستخدمين وإنشاء التعليقات +5. انسخ رمز المؤسسة من [إعدادات التكامل](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. تثبيت الحزمة المطلوبة + +```bash +uv add crewai-tools +``` + +### 3. إعداد متغير البيئة + + + لاستخدام التكاملات مع `Agent(apps=[])`, يجب تعيين متغير البيئة + `CREWAI_PLATFORM_INTEGRATION_TOKEN` برمز المؤسسة الخاص بك. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +أو أضفه إلى ملف `.env`: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## الإجراءات المتاحة + + + + **الوصف:** عرض جميع المستخدمين في مساحة العمل. + + **المعاملات:** + - `page_size` (integer, اختياري): عدد العناصر في الاستجابة. الحد الأدنى: 1، الحد الأقصى: 100، الافتراضي: 100 + - `start_cursor` (string, اختياري): مؤشر للترقيم. + + + + + **الوصف:** استرجاع مستخدم محدد بواسطة المعرّف. + + **المعاملات:** + - `user_id` (string, مطلوب): معرّف المستخدم المراد استرجاعه. + + + + + **الوصف:** إنشاء تعليق على صفحة أو مناقشة. + + **المعاملات:** + - `parent` (object, مطلوب): الصفحة الأصلية أو المناقشة للتعليق عليها. + ```json + { + "type": "page_id", + "page_id": "PAGE_ID_HERE" + } + ``` + - `rich_text` (array, مطلوب): المحتوى النصي الغني للتعليق. + ```json + [ + { + "type": "text", + "text": { + "content": "This is my comment text" + } + } + ] + ``` + + + + +## أمثلة الاستخدام + +### إعداد Agent أساسي لـ Notion + +```python +from crewai import Agent, Task, Crew + +# Create an agent with Notion capabilities +notion_agent = Agent( + role="Workspace Manager", + goal="Manage workspace users and facilitate collaboration through comments", + backstory="An AI assistant specialized in user management and team collaboration.", + apps=['notion'] # All Notion actions will be available +) + +# Task to list workspace users +user_management_task = Task( + description="List all users in the workspace and provide a summary of team members", + agent=notion_agent, + expected_output="Complete list of workspace users with their details" +) + +# Run the task +crew = Crew( + agents=[notion_agent], + tasks=[user_management_task] +) + +crew.kickoff() +``` + +## استكشاف الأخطاء وإصلاحها + +### المشاكل الشائعة + +**أخطاء الصلاحيات** + +- تأكد من أن حساب Notion الخاص بك لديه الصلاحيات المناسبة لقراءة معلومات المستخدمين +- تحقق من أن لديك صلاحيات التعليق على الصفحات أو المناقشات المستهدفة + +**مشاكل إنشاء التعليقات** + +- تحقق من صحة معرّفات الصفحات أو المناقشات وإمكانية الوصول إليها +- تأكد من اتباع محتوى النص الغني لمواصفات صيغة Notion API + +### الحصول على المساعدة + + + تواصل مع فريق الدعم للحصول على المساعدة في إعداد تكامل Notion أو + استكشاف الأخطاء وإصلاحها. + diff --git a/docs/ar/enterprise/integrations/salesforce.mdx b/docs/ar/enterprise/integrations/salesforce.mdx new file mode 100644 index 000000000..4e7dc060d --- /dev/null +++ b/docs/ar/enterprise/integrations/salesforce.mdx @@ -0,0 +1,331 @@ +--- +title: تكامل Salesforce +description: "أتمتة CRM والمبيعات مع تكامل Salesforce لـ CrewAI." +icon: "salesforce" +mode: "wide" +--- + +## نظرة عامة + +مكّن وكلاءك من إدارة علاقات العملاء وعمليات المبيعات والبيانات عبر Salesforce. أنشئ السجلات وحدّثها، وأدر العملاء المحتملين والفرص، ونفّذ استعلامات SOQL، وبسّط سير عمل CRM باستخدام الأتمتة المدعومة بالذكاء الاصطناعي. + +## المتطلبات الأساسية + +قبل استخدام تكامل Salesforce، تأكد من توفر ما يلي: + +- حساب [CrewAI AMP](https://app.crewai.com) مع اشتراك فعّال +- حساب Salesforce بالصلاحيات المناسبة +- ربط حساب Salesforce الخاص بك عبر [صفحة التكاملات](https://app.crewai.com/integrations) + +## إعداد تكامل Salesforce + +### 1. ربط حساب Salesforce الخاص بك + +1. انتقل إلى [تكاملات CrewAI AMP](https://app.crewai.com/crewai_plus/connectors) +2. ابحث عن **Salesforce** في قسم تكاملات المصادقة +3. انقر على **Connect** وأكمل عملية OAuth +4. امنح الصلاحيات اللازمة لإدارة CRM والمبيعات +5. انسخ رمز المؤسسة من [إعدادات التكامل](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. تثبيت الحزمة المطلوبة + +```bash +uv add crewai-tools +``` + +### 3. إعداد متغير البيئة + + + لاستخدام التكاملات مع `Agent(apps=[])`, يجب تعيين متغير البيئة + `CREWAI_PLATFORM_INTEGRATION_TOKEN` برمز المؤسسة الخاص بك. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +أو أضفه إلى ملف `.env`: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## الأدوات المتاحة + +### **إدارة السجلات** + + + + **الوصف:** إنشاء سجل جهة اتصال جديد في Salesforce. + + **المعاملات:** + - `LastName` (string, مطلوب): اسم العائلة - هذا الحقل مطلوب + - `FirstName` (string, اختياري): الاسم الأول + - `Email` (string, اختياري): عنوان البريد الإلكتروني + - `accountId` (string, اختياري): معرّف الحساب المرتبط + - `Title` (string, اختياري): المسمى الوظيفي + + + + + **الوصف:** إنشاء سجل عميل محتمل جديد في Salesforce. + + **المعاملات:** + - `LastName` (string, مطلوب): اسم العائلة - هذا الحقل مطلوب + - `Company` (string, مطلوب): الشركة - هذا الحقل مطلوب + - `FirstName` (string, اختياري): الاسم الأول + - `Email` (string, اختياري): عنوان البريد الإلكتروني + - `Status` (string, اختياري): حالة العميل المحتمل + + + + + **الوصف:** إنشاء سجل فرصة جديد في Salesforce. + + **المعاملات:** + - `Name` (string, مطلوب): اسم الفرصة - هذا الحقل مطلوب + - `StageName` (string, اختياري): مرحلة الفرصة + - `CloseDate` (string, اختياري): تاريخ الإغلاق بصيغة YYYY-MM-DD + - `Amount` (string, اختياري): المبلغ المقدر للبيع + + + + + **الوصف:** إنشاء سجل حساب جديد في Salesforce. + + **المعاملات:** + - `Name` (string, مطلوب): اسم الحساب - هذا الحقل مطلوب + - `Website` (string, اختياري): عنوان URL للموقع الإلكتروني + - `Phone` (string, اختياري): رقم الهاتف + - `Description` (string, اختياري): وصف الحساب + + + + + **الوصف:** إنشاء سجل مهمة جديد في Salesforce. + + **المعاملات:** + - `subject` (string, مطلوب): موضوع المهمة + - `taskSubtype` (string, مطلوب): النوع الفرعي للمهمة - الخيارات: task, email, listEmail, call + - `whatId` (string, اختياري): معرّف الحساب أو الفرصة المرتبطة + - `Status` (string, اختياري): الحالة - الخيارات: Not Started, In Progress, Completed + + + + +### **تحديث السجلات** + + + + **الوصف:** تحديث سجل جهة اتصال موجود في Salesforce. + + **المعاملات:** + - `recordId` (string, مطلوب): معرّف السجل المراد تحديثه + - `FirstName` (string, اختياري): الاسم الأول + - `LastName` (string, اختياري): اسم العائلة + - `Email` (string, اختياري): عنوان البريد الإلكتروني + + + + + **الوصف:** تحديث سجل عميل محتمل موجود في Salesforce. + + **المعاملات:** + - `recordId` (string, مطلوب): معرّف السجل المراد تحديثه + - `LastName` (string, اختياري): اسم العائلة + - `Company` (string, اختياري): اسم الشركة + - `Status` (string, اختياري): حالة العميل المحتمل + + + + + **الوصف:** تحديث سجل فرصة موجود في Salesforce. + + **المعاملات:** + - `recordId` (string, مطلوب): معرّف السجل المراد تحديثه + - `Name` (string, اختياري): اسم الفرصة + - `StageName` (string, اختياري): مرحلة الفرصة + - `Amount` (string, اختياري): المبلغ المقدر + + + + + **الوصف:** تحديث سجل حساب موجود في Salesforce. + + **المعاملات:** + - `recordId` (string, مطلوب): معرّف السجل المراد تحديثه + - `Name` (string, اختياري): اسم الحساب + - `Website` (string, اختياري): عنوان URL للموقع الإلكتروني + + + + +### **استرجاع السجلات** + + + + **الوصف:** الحصول على سجل جهة اتصال بواسطة معرّفه. + + **المعاملات:** + - `recordId` (string, مطلوب): معرّف سجل جهة الاتصال + + + + + **الوصف:** الحصول على سجل عميل محتمل بواسطة معرّفه. + + **المعاملات:** + - `recordId` (string, مطلوب): معرّف سجل العميل المحتمل + + + + + **الوصف:** الحصول على سجل فرصة بواسطة معرّفه. + + **المعاملات:** + - `recordId` (string, مطلوب): معرّف سجل الفرصة + + + + + **الوصف:** الحصول على سجل حساب بواسطة معرّفه. + + **المعاملات:** + - `recordId` (string, مطلوب): معرّف سجل الحساب + + + + +### **البحث في السجلات** + + + + **الوصف:** البحث عن سجلات جهات الاتصال بتصفية متقدمة. + + **المعاملات:** + - `filterFormula` (object, اختياري): فلتر متقدم بصيغة التعبير العادي المنفصل + - `sortBy` (string, اختياري): حقل الفرز + - `sortDirection` (string, اختياري): اتجاه الفرز - الخيارات: ASC, DESC + + + + + **الوصف:** البحث عن سجلات العملاء المحتملين بتصفية متقدمة. + + **المعاملات:** + - `filterFormula` (object, اختياري): فلتر متقدم + - `sortBy` (string, اختياري): حقل الفرز + + + + + **الوصف:** البحث عن سجلات الفرص بتصفية متقدمة. + + **المعاملات:** + - `filterFormula` (object, اختياري): فلتر متقدم + - `sortBy` (string, اختياري): حقل الفرز + + + + +### **العمليات المتقدمة** + + + + **الوصف:** تنفيذ استعلامات SOQL مخصصة على بيانات Salesforce. + + **المعاملات:** + - `query` (string, مطلوب): استعلام SOQL (مثال: "SELECT Id, Name FROM Account WHERE Name = 'Example'") + + + + + **الوصف:** نشر كائن مخصص جديد في Salesforce. + + **المعاملات:** + - `label` (string, مطلوب): تسمية الكائن + - `pluralLabel` (string, مطلوب): التسمية الجمعية + - `recordName` (string, مطلوب): اسم السجل + + + + + **الوصف:** الحصول على المخطط المتوقع لعمليات على أنواع كائنات محددة. + + **المعاملات:** + - `recordType` (string, مطلوب): نوع السجل المراد وصفه + - `operation` (string, مطلوب): نوع العملية (مثال: "CREATE_RECORD" أو "UPDATE_RECORD") + + + + +## أمثلة الاستخدام + +### إعداد Agent أساسي لـ Salesforce + +```python +from crewai import Agent, Task, Crew +from crewai import Agent, Task, Crew + +# Create an agent with Salesforce capabilities +salesforce_agent = Agent( + role="CRM Manager", + goal="Manage customer relationships and sales processes efficiently", + backstory="An AI assistant specialized in CRM operations and sales automation.", + apps=['salesforce'] # All Salesforce actions will be available +) + +# Task to create a new lead +create_lead_task = Task( + description="Create a new lead for John Doe from Example Corp with email john.doe@example.com", + agent=salesforce_agent, + expected_output="Lead created successfully with lead ID" +) + +# Run the task +crew = Crew( + agents=[salesforce_agent], + tasks=[create_lead_task] +) + +crew.kickoff() +``` + +### استعلامات SOQL المتقدمة وإعداد التقارير + +```python +from crewai import Agent, Task, Crew + +data_analyst = Agent( + role="Sales Data Analyst", + goal="Generate insights from Salesforce data using SOQL queries", + backstory="An analytical AI that excels at extracting meaningful insights from CRM data.", + apps=['salesforce'] +) + +# Complex task involving SOQL queries and data analysis +analysis_task = Task( + description=""" + 1. Execute a SOQL query to find all opportunities closing this quarter + 2. Search for contacts at companies with opportunities over $100K + 3. Create a summary report of the sales pipeline status + 4. Update high-value opportunities with next steps + """, + agent=data_analyst, + expected_output="Comprehensive sales pipeline analysis with actionable insights" +) + +crew = Crew( + agents=[data_analyst], + tasks=[analysis_task] +) + +crew.kickoff() +``` + +### الحصول على المساعدة + + + تواصل مع فريق الدعم للحصول على المساعدة في إعداد تكامل Salesforce أو + استكشاف الأخطاء وإصلاحها. + diff --git a/docs/ar/enterprise/integrations/shopify.mdx b/docs/ar/enterprise/integrations/shopify.mdx new file mode 100644 index 000000000..fdd790a44 --- /dev/null +++ b/docs/ar/enterprise/integrations/shopify.mdx @@ -0,0 +1,196 @@ +--- +title: تكامل Shopify +description: "إدارة التجارة الإلكترونية والمتجر الإلكتروني مع تكامل Shopify لـ CrewAI." +icon: "shopify" +mode: "wide" +--- + +## نظرة عامة + +مكّن وكلاءك من إدارة عمليات التجارة الإلكترونية عبر Shopify. تعامل مع العملاء والطلبات والمنتجات والمخزون وتحليلات المتجر لتبسيط أعمالك التجارية عبر الإنترنت باستخدام الأتمتة المدعومة بالذكاء الاصطناعي. + +## المتطلبات الأساسية + +قبل استخدام تكامل Shopify، تأكد من توفر ما يلي: + +- حساب [CrewAI AMP](https://app.crewai.com) مع اشتراك فعّال +- متجر Shopify بصلاحيات المسؤول المناسبة +- ربط متجر Shopify الخاص بك عبر [صفحة التكاملات](https://app.crewai.com/integrations) + +## إعداد تكامل Shopify + +### 1. ربط متجر Shopify الخاص بك + +1. انتقل إلى [تكاملات CrewAI AMP](https://app.crewai.com/crewai_plus/connectors) +2. ابحث عن **Shopify** في قسم تكاملات المصادقة +3. انقر على **Connect** وأكمل عملية OAuth +4. امنح الصلاحيات اللازمة لإدارة المتجر والمنتجات +5. انسخ رمز المؤسسة من [إعدادات التكامل](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. تثبيت الحزمة المطلوبة + +```bash +uv add crewai-tools +``` + +### 3. إعداد متغير البيئة + + + لاستخدام التكاملات مع `Agent(apps=[])`, يجب تعيين متغير البيئة + `CREWAI_PLATFORM_INTEGRATION_TOKEN` برمز المؤسسة الخاص بك. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +أو أضفه إلى ملف `.env`: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## الأدوات المتاحة + +### **إدارة العملاء** + + + + **الوصف:** استرجاع قائمة العملاء من متجر Shopify. + + **المعاملات:** + - `customerIds` (string, اختياري): قائمة معرّفات العملاء مفصولة بفواصل + - `limit` (string, اختياري): الحد الأقصى لعدد العملاء (الافتراضي: 250) + + + + + **الوصف:** إنشاء عميل جديد في متجر Shopify. + + **المعاملات:** + - `firstName` (string, مطلوب): الاسم الأول للعميل + - `lastName` (string, مطلوب): اسم العائلة للعميل + - `email` (string, مطلوب): عنوان البريد الإلكتروني للعميل + - `phone` (string, اختياري): رقم الهاتف + - `tags` (string, اختياري): الوسوم كمصفوفة أو قائمة مفصولة بفواصل + + + + + **الوصف:** تحديث عميل موجود في متجر Shopify. + + **المعاملات:** + - `customerId` (string, مطلوب): معرّف العميل المراد تحديثه + - `firstName` (string, اختياري): الاسم الأول + - `lastName` (string, اختياري): اسم العائلة + - `email` (string, اختياري): عنوان البريد الإلكتروني + + + + +### **إدارة الطلبات** + + + + **الوصف:** استرجاع قائمة الطلبات من متجر Shopify. + + **المعاملات:** + - `orderIds` (string, اختياري): قائمة معرّفات الطلبات مفصولة بفواصل + - `limit` (string, اختياري): الحد الأقصى لعدد الطلبات (الافتراضي: 250) + + + + + **الوصف:** إنشاء طلب جديد في متجر Shopify. + + **المعاملات:** + - `email` (string, مطلوب): عنوان البريد الإلكتروني للعميل + - `lineItems` (object, مطلوب): عناصر سطر الطلب بصيغة JSON + - `fulfillmentStatus` (string, اختياري): حالة التنفيذ - الخيارات: fulfilled, null, partial, restocked + + + + + **الوصف:** استرجاع سلال التسوق المهجورة من متجر Shopify. + + **المعاملات:** + - `status` (string, اختياري): عرض عمليات الدفع بالحالة المحددة - الخيارات: open, closed (الافتراضي: open) + - `limit` (string, اختياري): الحد الأقصى لعدد السلال (الافتراضي: 250) + + + + +### **إدارة المنتجات** + + + + **الوصف:** استرجاع قائمة المنتجات من متجر Shopify. + + **المعاملات:** + - `title` (string, اختياري): تصفية حسب عنوان المنتج + - `status` (string, اختياري): تصفية حسب الحالة - الخيارات: active, archived, draft + - `limit` (string, اختياري): الحد الأقصى لعدد المنتجات (الافتراضي: 250) + + + + + **الوصف:** إنشاء منتج جديد في متجر Shopify. + + **المعاملات:** + - `title` (string, مطلوب): عنوان المنتج + - `productType` (string, مطلوب): نوع/فئة المنتج + - `vendor` (string, مطلوب): مورد المنتج + - `productDescription` (string, اختياري): وصف المنتج + - `price` (string, اختياري): سعر المنتج + + + + + **الوصف:** تحديث منتج موجود في متجر Shopify. + + **المعاملات:** + - `productId` (string, مطلوب): معرّف المنتج المراد تحديثه + - `title` (string, اختياري): عنوان المنتج + - `price` (string, اختياري): سعر المنتج + + + + +## أمثلة الاستخدام + +### إعداد Agent أساسي لـ Shopify + +```python +from crewai import Agent, Task, Crew +from crewai import Agent, Task, Crew + +# Create an agent with Shopify capabilities +shopify_agent = Agent( + role="E-commerce Manager", + goal="Manage online store operations and customer relationships efficiently", + backstory="An AI assistant specialized in e-commerce operations and online store management.", + apps=['shopify'] # All Shopify actions will be available +) + +# Task to create a new customer +create_customer_task = Task( + description="Create a new VIP customer Jane Smith with email jane.smith@example.com and phone +1-555-0123", + agent=shopify_agent, + expected_output="Customer created successfully with customer ID" +) + +# Run the task +crew = Crew( + agents=[shopify_agent], + tasks=[create_customer_task] +) + +crew.kickoff() +``` + +### الحصول على المساعدة + + + تواصل مع فريق الدعم للحصول على المساعدة في إعداد تكامل Shopify أو + استكشاف الأخطاء وإصلاحها. + diff --git a/docs/ar/enterprise/integrations/slack.mdx b/docs/ar/enterprise/integrations/slack.mdx new file mode 100644 index 000000000..bc3835c6e --- /dev/null +++ b/docs/ar/enterprise/integrations/slack.mdx @@ -0,0 +1,170 @@ +--- +title: تكامل Slack +description: "التواصل الجماعي والتعاون مع تكامل Slack لـ CrewAI." +icon: "slack" +mode: "wide" +--- + +## نظرة عامة + +مكّن وكلاءك من إدارة التواصل الجماعي عبر Slack. أرسل الرسائل، وابحث في المحادثات، وأدر القنوات، ونسّق أنشطة الفريق لتبسيط سير عمل التعاون باستخدام الأتمتة المدعومة بالذكاء الاصطناعي. + +## المتطلبات الأساسية + +قبل استخدام تكامل Slack، تأكد من توفر ما يلي: + +- حساب [CrewAI AMP](https://app.crewai.com) مع اشتراك فعّال +- مساحة عمل Slack بالصلاحيات المناسبة +- ربط مساحة عمل Slack الخاصة بك عبر [صفحة التكاملات](https://app.crewai.com/integrations) + +## إعداد تكامل Slack + +### 1. ربط مساحة عمل Slack الخاصة بك + +1. انتقل إلى [تكاملات CrewAI AMP](https://app.crewai.com/crewai_plus/connectors) +2. ابحث عن **Slack** في قسم تكاملات المصادقة +3. انقر على **Connect** وأكمل عملية OAuth +4. امنح الصلاحيات اللازمة للتواصل الجماعي +5. انسخ رمز المؤسسة من [إعدادات التكامل](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. تثبيت الحزمة المطلوبة + +```bash +uv add crewai-tools +``` + +### 3. إعداد متغير البيئة + + + لاستخدام التكاملات مع `Agent(apps=[])`, يجب تعيين متغير البيئة + `CREWAI_PLATFORM_INTEGRATION_TOKEN` برمز المؤسسة الخاص بك. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +أو أضفه إلى ملف `.env`: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## الأدوات المتاحة + +### **إدارة المستخدمين** + + + + **الوصف:** عرض جميع الأعضاء في قناة Slack. + + **المعاملات:** + - لا توجد معاملات مطلوبة + + + + + **الوصف:** البحث عن مستخدم في مساحة عمل Slack بواسطة عنوان بريده الإلكتروني. + + **المعاملات:** + - `email` (string, مطلوب): عنوان البريد الإلكتروني للمستخدم في مساحة العمل + + + + + **الوصف:** البحث عن المستخدمين بواسطة اسمهم أو اسم العرض. + + **المعاملات:** + - `name` (string, مطلوب): الاسم الحقيقي للمستخدم للبحث عنه + - `displayName` (string, مطلوب): اسم عرض المستخدم للبحث عنه + + + + +### **إدارة القنوات** + + + + **الوصف:** عرض جميع القنوات في مساحة عمل Slack. + + **المعاملات:** + - لا توجد معاملات مطلوبة + + + + +### **المراسلة** + + + + **الوصف:** إرسال رسالة إلى قناة Slack. + + **المعاملات:** + - `channel` (string, مطلوب): اسم القناة أو معرّفها + - `message` (string, مطلوب): نص الرسالة المراد إرسالها + - `botName` (string, مطلوب): اسم البوت الذي يرسل هذه الرسالة + - `botIcon` (string, مطلوب): أيقونة البوت - يمكن أن تكون عنوان URL لصورة أو رمز تعبيري + + + + + **الوصف:** إرسال رسالة مباشرة إلى مستخدم محدد في Slack. + + **المعاملات:** + - `memberId` (string, مطلوب): معرّف المستخدم المستلم + - `message` (string, مطلوب): نص الرسالة المراد إرسالها + - `botName` (string, مطلوب): اسم البوت الذي يرسل هذه الرسالة + - `botIcon` (string, مطلوب): أيقونة البوت + + + + +### **البحث والاكتشاف** + + + + **الوصف:** البحث عن الرسائل عبر مساحة عمل Slack. + + **المعاملات:** + - `query` (string, مطلوب): استعلام بحث باستخدام صيغة بحث Slack للعثور على الرسائل المطابقة + + + + +## أمثلة الاستخدام + +### إعداد Agent أساسي لـ Slack + +```python +from crewai import Agent, Task, Crew + +# Create an agent with Slack capabilities +slack_agent = Agent( + role="Team Communication Manager", + goal="Facilitate team communication and coordinate collaboration efficiently", + backstory="An AI assistant specialized in team communication and workspace coordination.", + apps=['slack'] # All Slack actions will be available +) + +# Task to send project updates +update_task = Task( + description="Send a project status update to the #general channel with current progress", + agent=slack_agent, + expected_output="Project update message sent successfully to team channel" +) + +# Run the task +crew = Crew( + agents=[slack_agent], + tasks=[update_task] +) + +crew.kickoff() +``` + +## التواصل مع الدعم + + + تواصل مع فريق الدعم للحصول على المساعدة في إعداد تكامل Slack أو + استكشاف الأخطاء وإصلاحها. + diff --git a/docs/ar/enterprise/integrations/stripe.mdx b/docs/ar/enterprise/integrations/stripe.mdx new file mode 100644 index 000000000..26252a4ef --- /dev/null +++ b/docs/ar/enterprise/integrations/stripe.mdx @@ -0,0 +1,202 @@ +--- +title: تكامل Stripe +description: "معالجة المدفوعات وإدارة الاشتراكات مع تكامل Stripe لـ CrewAI." +icon: "stripe" +mode: "wide" +--- + +## نظرة عامة + +مكّن وكلاءك من إدارة المدفوعات والاشتراكات وفواتير العملاء عبر Stripe. تعامل مع بيانات العملاء، ومعالجة الاشتراكات، وإدارة المنتجات، وتتبع المعاملات المالية لتبسيط سير عمل المدفوعات باستخدام الأتمتة المدعومة بالذكاء الاصطناعي. + +## المتطلبات الأساسية + +قبل استخدام تكامل Stripe، تأكد من توفر ما يلي: + +- حساب [CrewAI AMP](https://app.crewai.com) مع اشتراك فعّال +- حساب Stripe بصلاحيات API المناسبة +- ربط حساب Stripe الخاص بك عبر [صفحة التكاملات](https://app.crewai.com/integrations) + +## إعداد تكامل Stripe + +### 1. ربط حساب Stripe الخاص بك + +1. انتقل إلى [تكاملات CrewAI AMP](https://app.crewai.com/crewai_plus/connectors) +2. ابحث عن **Stripe** في قسم تكاملات المصادقة +3. انقر على **Connect** وأكمل عملية OAuth +4. امنح الصلاحيات اللازمة لمعالجة المدفوعات +5. انسخ رمز المؤسسة من [إعدادات التكامل](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. تثبيت الحزمة المطلوبة + +```bash +uv add crewai-tools +``` + +### 3. إعداد متغير البيئة + + + لاستخدام التكاملات مع `Agent(apps=[])`, يجب تعيين متغير البيئة + `CREWAI_PLATFORM_INTEGRATION_TOKEN` برمز المؤسسة الخاص بك. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +أو أضفه إلى ملف `.env`: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## الأدوات المتاحة + +### **إدارة العملاء** + + + + **الوصف:** إنشاء عميل جديد في حساب Stripe. + + **المعاملات:** + - `emailCreateCustomer` (string, مطلوب): عنوان البريد الإلكتروني للعميل + - `name` (string, اختياري): الاسم الكامل للعميل + - `description` (string, اختياري): وصف العميل للمرجع الداخلي + + + + + **الوصف:** استرجاع عميل محدد بواسطة معرّف عميل Stripe. + + **المعاملات:** + - `idGetCustomer` (string, مطلوب): معرّف عميل Stripe المراد استرجاعه + + + + + **الوصف:** استرجاع قائمة العملاء مع تصفية اختيارية. + + **المعاملات:** + - `emailGetCustomers` (string, اختياري): تصفية العملاء حسب البريد الإلكتروني + - `limitGetCustomers` (string, اختياري): الحد الأقصى لعدد العملاء (الافتراضي: 10) + + + + + **الوصف:** تحديث معلومات عميل موجود. + + **المعاملات:** + - `customerId` (string, مطلوب): معرّف العميل المراد تحديثه + - `emailUpdateCustomer` (string, اختياري): عنوان البريد الإلكتروني المحدّث + - `name` (string, اختياري): اسم العميل المحدّث + + + + +### **إدارة الاشتراكات** + + + + **الوصف:** إنشاء اشتراك جديد لعميل. + + **المعاملات:** + - `customerIdCreateSubscription` (string, مطلوب): معرّف العميل الذي سيُنشأ له الاشتراك + - `plan` (string, مطلوب): معرّف خطة الاشتراك + + + + + **الوصف:** استرجاع الاشتراكات مع تصفية اختيارية. + + **المعاملات:** + - `customerIdGetSubscriptions` (string, اختياري): تصفية الاشتراكات حسب معرّف العميل + - `subscriptionStatus` (string, اختياري): تصفية حسب حالة الاشتراك - الخيارات: incomplete, trialing, active, past_due, canceled, unpaid + + + + +### **إدارة المنتجات** + + + + **الوصف:** إنشاء منتج جديد في كتالوج Stripe. + + **المعاملات:** + - `productName` (string, مطلوب): اسم المنتج + - `description` (string, اختياري): وصف المنتج + + + + + **الوصف:** استرجاع قائمة المنتجات مع تصفية اختيارية. + + **المعاملات:** + - `limitGetProducts` (string, اختياري): الحد الأقصى لعدد المنتجات (الافتراضي: 10) + + + + +### **العمليات المالية** + + + + **الوصف:** استرجاع معاملات الرصيد من حساب Stripe. + + **المعاملات:** + - `balanceTransactionType` (string, اختياري): تصفية حسب نوع المعاملة - الخيارات: charge, refund, payment, payment_refund + + + + + **الوصف:** استرجاع خطط الاشتراك من حساب Stripe. + + **المعاملات:** + - `isPlanActive` (boolean, اختياري): تصفية حسب حالة الخطة + + + + +## أمثلة الاستخدام + +### إعداد Agent أساسي لـ Stripe + +```python +from crewai import Agent, Task, Crew +from crewai import Agent, Task, Crew + +# Create an agent with Stripe capabilities +stripe_agent = Agent( + role="Payment Manager", + goal="Manage customer payments, subscriptions, and billing operations efficiently", + backstory="An AI assistant specialized in payment processing and subscription management.", + apps=['stripe'] # All Stripe actions will be available +) + +# Task to create a new customer +create_customer_task = Task( + description="Create a new premium customer John Doe with email john.doe@example.com", + agent=stripe_agent, + expected_output="Customer created successfully with customer ID" +) + +# Run the task +crew = Crew( + agents=[stripe_agent], + tasks=[create_customer_task] +) + +crew.kickoff() +``` + +## مرجع حالات الاشتراك + +فهم حالات الاشتراك: + +- **incomplete** - الاشتراك يتطلب طريقة دفع أو تأكيد الدفع +- **trialing** - الاشتراك في فترة تجريبية +- **active** - الاشتراك نشط وحالي +- **past_due** - فشل الدفع لكن الاشتراك لا يزال نشطاً +- **canceled** - تم إلغاء الاشتراك +- **unpaid** - فشل الدفع والاشتراك لم يعد نشطاً + +يمكّن هذا التكامل أتمتة شاملة لإدارة المدفوعات والاشتراكات، مما يسمح لوكلاء الذكاء الاصطناعي بالتعامل مع عمليات الفوترة بسلاسة ضمن نظام Stripe البيئي. diff --git a/docs/ar/enterprise/integrations/zendesk.mdx b/docs/ar/enterprise/integrations/zendesk.mdx new file mode 100644 index 000000000..000a6e4c4 --- /dev/null +++ b/docs/ar/enterprise/integrations/zendesk.mdx @@ -0,0 +1,262 @@ +--- +title: تكامل Zendesk +description: "دعم العملاء وإدارة مكتب المساعدة مع تكامل Zendesk لـ CrewAI." +icon: "headset" +mode: "wide" +--- + +## نظرة عامة + +مكّن وكلاءك من إدارة عمليات دعم العملاء عبر Zendesk. أنشئ التذاكر وحدّثها، وأدر المستخدمين، وتتبع مقاييس الدعم، وبسّط سير عمل خدمة العملاء باستخدام الأتمتة المدعومة بالذكاء الاصطناعي. + +## المتطلبات الأساسية + +قبل استخدام تكامل Zendesk، تأكد من توفر ما يلي: + +- حساب [CrewAI AMP](https://app.crewai.com) مع اشتراك فعّال +- حساب Zendesk بصلاحيات API المناسبة +- ربط حساب Zendesk الخاص بك عبر [صفحة التكاملات](https://app.crewai.com/integrations) + +## إعداد تكامل Zendesk + +### 1. ربط حساب Zendesk الخاص بك + +1. انتقل إلى [تكاملات CrewAI AMP](https://app.crewai.com/crewai_plus/connectors) +2. ابحث عن **Zendesk** في قسم تكاملات المصادقة +3. انقر على **Connect** وأكمل عملية OAuth +4. امنح الصلاحيات اللازمة لإدارة التذاكر والمستخدمين +5. انسخ رمز المؤسسة من [إعدادات التكامل](https://app.crewai.com/crewai_plus/settings/integrations) + +### 2. تثبيت الحزمة المطلوبة + +```bash +uv add crewai-tools +``` + +### 3. إعداد متغير البيئة + + + لاستخدام التكاملات مع `Agent(apps=[])`, يجب تعيين متغير البيئة + `CREWAI_PLATFORM_INTEGRATION_TOKEN` برمز المؤسسة الخاص بك. + + +```bash +export CREWAI_PLATFORM_INTEGRATION_TOKEN="your_enterprise_token" +``` + +أو أضفه إلى ملف `.env`: + +``` +CREWAI_PLATFORM_INTEGRATION_TOKEN=your_enterprise_token +``` + +## الأدوات المتاحة + +### **إدارة التذاكر** + + + + **الوصف:** إنشاء تذكرة دعم جديدة في Zendesk. + + **المعاملات:** + - `ticketSubject` (string, مطلوب): سطر موضوع التذكرة + - `ticketDescription` (string, مطلوب): أول تعليق يظهر على التذكرة + - `requesterName` (string, مطلوب): اسم المستخدم الذي يطلب الدعم + - `requesterEmail` (string, مطلوب): بريد المستخدم الذي يطلب الدعم + - `ticketType` (string, اختياري): نوع التذكرة - الخيارات: problem, incident, question, task + - `ticketPriority` (string, اختياري): مستوى الأولوية - الخيارات: urgent, high, normal, low + - `ticketStatus` (string, اختياري): حالة التذكرة - الخيارات: new, open, pending, hold, solved, closed + + + + + **الوصف:** تحديث تذكرة دعم موجودة في Zendesk. + + **المعاملات:** + - `ticketId` (string, مطلوب): معرّف التذكرة المراد تحديثها + - `requesterName` (string, مطلوب): اسم المستخدم الذي طلب هذه التذكرة + - `requesterEmail` (string, مطلوب): بريد المستخدم الذي طلب هذه التذكرة + - `ticketSubject` (string, اختياري): موضوع التذكرة المحدّث + - `ticketPriority` (string, اختياري): الأولوية المحدّثة + - `ticketStatus` (string, اختياري): الحالة المحدّثة + + + + + **الوصف:** استرجاع تذكرة محددة بواسطة معرّفها. + + **المعاملات:** + - `ticketId` (string, مطلوب): معرّف التذكرة المراد استرجاعها + + + + + **الوصف:** إضافة تعليق أو ملاحظة داخلية إلى تذكرة موجودة. + + **المعاملات:** + - `ticketId` (string, مطلوب): معرّف التذكرة لإضافة التعليق إليها + - `commentBody` (string, مطلوب): رسالة التعليق + - `isInternalNote` (boolean, اختياري): عيّن إلى true للملاحظات الداخلية بدلاً من الردود العامة + + + + + **الوصف:** البحث عن التذاكر باستخدام فلاتر ومعايير مختلفة. + + **المعاملات:** + - `ticketSubject` (string, اختياري): تصفية حسب النص في موضوع التذكرة + - `ticketStatus` (string, اختياري): تصفية حسب الحالة + - `ticketPriority` (string, اختياري): تصفية حسب الأولوية + - `sort_by` (string, اختياري): حقل الفرز - الخيارات: created_at, updated_at, priority, status + - `sort_order` (string, اختياري): اتجاه الفرز - الخيارات: asc, desc + + + + +### **إدارة المستخدمين** + + + + **الوصف:** إنشاء مستخدم جديد في Zendesk. + + **المعاملات:** + - `name` (string, مطلوب): الاسم الكامل للمستخدم + - `email` (string, اختياري): عنوان البريد الإلكتروني + - `phone` (string, اختياري): رقم الهاتف + - `role` (string, اختياري): دور المستخدم - الخيارات: admin, agent, end-user + + + + + **الوصف:** تحديث معلومات مستخدم موجود. + + **المعاملات:** + - `userId` (string, مطلوب): معرّف المستخدم المراد تحديثه + - `name` (string, اختياري): اسم المستخدم المحدّث + - `email` (string, اختياري): البريد الإلكتروني المحدّث + - `role` (string, اختياري): الدور المحدّث + + + + + **الوصف:** استرجاع مستخدم محدد بواسطة معرّفه. + + **المعاملات:** + - `userId` (string, مطلوب): معرّف المستخدم المراد استرجاعه + + + + + **الوصف:** البحث عن المستخدمين باستخدام معايير مختلفة. + + **المعاملات:** + - `name` (string, اختياري): تصفية حسب اسم المستخدم + - `email` (string, اختياري): تصفية حسب البريد الإلكتروني + - `role` (string, اختياري): تصفية حسب الدور + + + + +### **أدوات إدارية** + + + + **الوصف:** استرجاع جميع الحقول القياسية والمخصصة المتاحة للتذاكر. + + **المعاملات:** + - `paginationParameters` (object, اختياري): إعدادات الترقيم + + + + + **الوصف:** الحصول على سجلات التدقيق (السجل للقراءة فقط) للتذاكر. + + **المعاملات:** + - `ticketId` (string, اختياري): الحصول على سجلات التدقيق لتذكرة محددة + + + + +## مستويات أولوية التذاكر + +فهم مستويات الأولوية: + +- **urgent** - مشاكل حرجة تتطلب اهتماماً فورياً +- **high** - مشاكل مهمة يجب معالجتها بسرعة +- **normal** - أولوية قياسية لمعظم التذاكر +- **low** - مشاكل ثانوية يمكن معالجتها عند الإمكان + +## سير عمل حالة التذكرة + +تقدم حالة التذكرة القياسي: + +- **new** - أُنشئت حديثاً، لم تُعيّن بعد +- **open** - يتم العمل عليها بنشاط +- **pending** - في انتظار رد العميل أو إجراء خارجي +- **hold** - متوقفة مؤقتاً +- **solved** - تم حل المشكلة، في انتظار تأكيد العميل +- **closed** - اكتملت التذكرة وأُغلقت + +## أمثلة الاستخدام + +### إعداد Agent أساسي لـ Zendesk + +```python +from crewai import Agent, Task, Crew +from crewai import Agent, Task, Crew + +# Create an agent with Zendesk capabilities +zendesk_agent = Agent( + role="Support Manager", + goal="Manage customer support tickets and provide excellent customer service", + backstory="An AI assistant specialized in customer support operations and ticket management.", + apps=['zendesk'] # All Zendesk actions will be available +) + +# Task to create a new support ticket +create_ticket_task = Task( + description="Create a high-priority support ticket for John Smith who is unable to access his account after password reset", + agent=zendesk_agent, + expected_output="Support ticket created successfully with ticket ID" +) + +# Run the task +crew = Crew( + agents=[zendesk_agent], + tasks=[create_ticket_task] +) + +crew.kickoff() +``` + +### إدارة التذاكر المتقدمة + +```python +from crewai import Agent, Task, Crew + +ticket_manager = Agent( + role="Ticket Manager", + goal="Manage support ticket workflows and ensure timely resolution", + backstory="An AI assistant that specializes in support ticket triage and workflow optimization.", + apps=['zendesk'] +) + +# Task to manage ticket lifecycle +ticket_workflow = Task( + description=""" + 1. Create a new support ticket for account access issues + 2. Add internal notes with troubleshooting steps + 3. Update ticket priority based on customer tier + 4. Add resolution comments and close the ticket + """, + agent=ticket_manager, + expected_output="Complete ticket lifecycle managed from creation to resolution" +) + +crew = Crew( + agents=[ticket_manager], + tasks=[ticket_workflow] +) + +crew.kickoff() +``` diff --git a/docs/ar/enterprise/introduction.mdx b/docs/ar/enterprise/introduction.mdx new file mode 100644 index 000000000..1d0b15c76 --- /dev/null +++ b/docs/ar/enterprise/introduction.mdx @@ -0,0 +1,99 @@ +--- +title: "CrewAI AMP" +description: "نشر ومراقبة وتوسيع سير عمل وكلاء الذكاء الاصطناعي" +icon: "globe" +mode: "wide" +--- + +## مقدمة + +توفر منصة CrewAI AMP (منصة إدارة الوكلاء) بيئة لنشر ومراقبة وتوسيع أطقمك ووكلائك في بيئة إنتاجية. + + + لوحة تحكم CrewAI AMP + + +تعمل منصة CrewAI AMP على توسيع قوة إطار العمل مفتوح المصدر بميزات مصممة لعمليات النشر الإنتاجية والتعاون وقابلية التوسع. انشر أطقمك على بنية تحتية مُدارة وراقب تنفيذها في الوقت الفعلي. + +## الميزات الرئيسية + + + + انشر أطقمك على بنية تحتية مُدارة بنقرات قليلة + + + الوصول إلى أطقمك المنشورة عبر REST API للتكامل مع الأنظمة الحالية + + + راقب أطقمك مع تتبع تفصيلي للتنفيذ والسجلات + + + انشر وثبّت الأدوات لتعزيز قدرات أطقمك + + + بث الأحداث والتحديثات في الوقت الفعلي إلى أنظمتك + + + أنشئ وخصص الأطقم باستخدام واجهة بدون كود/منخفضة الكود + + + +## خيارات النشر + + + + اتصل مباشرة بمستودعات GitHub الخاصة بك لنشر الكود + + + انشر الأطقم المنشأة عبر واجهة استوديو الأطقم بدون كود + + + استخدم واجهة سطر أوامر CrewAI لسير عمل نشر أكثر تقدمًا + + + +## البدء + + + + أنشئ حسابك على [app.crewai.com](https://app.crewai.com) + + التسجيل + + + + استخدم الكود أو استوديو الأطقم لبناء طاقمك + + بناء طاقم + + + + انشر طاقمك على منصة Enterprise + + نشر طاقم + + + + تكامل مع طاقمك عبر نقاط نهاية API المُنشأة + + استخدام API الطاقم + + + + +للحصول على تعليمات مفصلة، اطلع على [دليل النشر](/ar/enterprise/guides/deploy-to-amp) أو انقر على الزر أدناه للبدء. diff --git a/docs/ar/enterprise/resources/frequently-asked-questions.mdx b/docs/ar/enterprise/resources/frequently-asked-questions.mdx new file mode 100644 index 000000000..65cc02c80 --- /dev/null +++ b/docs/ar/enterprise/resources/frequently-asked-questions.mdx @@ -0,0 +1,152 @@ +--- +title: الأسئلة الشائعة +description: "الأسئلة المتكررة حول CrewAI AMP" +icon: "circle-question" +mode: "wide" +--- + + + + في العملية الهرمية، يتم إنشاء وكيل مدير تلقائيًا ينسق سير العمل، ويفوض المهام ويتحقق من النتائج لتنفيذ مبسط وفعال. يستخدم وكيل المدير الأدوات لتسهيل تفويض المهام وتنفيذها بواسطة الوكلاء تحت إشراف المدير. يُعد نموذج اللغة الخاص بالمدير (LLM) أساسيًا للعملية الهرمية ويجب إعداده بشكل صحيح لضمان العمل السليم. + + + + يتوفر أحدث توثيق لـ CrewAI على موقع التوثيق الرسمي: https://docs.crewai.com/ + توثيق CrewAI + + + + #### العملية الهرمية: + - يتم تفويض المهام وتنفيذها بناءً على سلسلة قيادة منظمة + - يجب تحديد نموذج لغة المدير (`manager_llm`) لوكيل المدير + - يشرف وكيل المدير على تنفيذ المهام والتخطيط والتفويض والتحقق + - لا يتم تعيين المهام مسبقًا؛ يقوم المدير بتخصيص المهام للوكلاء بناءً على قدراتهم + + #### العملية التسلسلية: + - يتم تنفيذ المهام واحدة تلو الأخرى، مما يضمن إكمال المهام بتقدم منظم + - يُستخدم مخرج مهمة واحدة كسياق للمهمة التالية + - يتبع تنفيذ المهام الترتيب المحدد مسبقًا في قائمة المهام + + #### أي عملية أفضل للمشاريع المعقدة؟ + العملية الهرمية أنسب للمشاريع المعقدة لأنها تسمح بـ: + - **تخصيص وتفويض ديناميكي للمهام**: يمكن لوكيل المدير تعيين المهام بناءً على قدرات الوكلاء + - **التحقق والإشراف المنظم**: يراجع وكيل المدير مخرجات المهام ويضمن إكمالها + - **إدارة المهام المعقدة**: تحكم دقيق في توفر الأدوات على مستوى الوكيل + + + + - **التعلم التكيفي**: تصبح الأطقم أكثر كفاءة بمرور الوقت، حيث تتكيف مع المعلومات الجديدة وتحسن نهجها في المهام + - **التخصيص المحسن**: تمكّن الذاكرة الوكلاء من تذكر تفضيلات المستخدم والتفاعلات السابقة، مما يؤدي إلى تجارب مخصصة + - **تحسين حل المشكلات**: يساعد الوصول إلى مخزن ذاكرة غني الوكلاء في اتخاذ قرارات أكثر استنارة، بالاعتماد على الدروس المستفادة والرؤى السياقية + + + + يمنع تعيين حد أقصى لعدد الطلبات في الدقيقة للوكيل من إجراء عدد كبير جدًا من الطلبات إلى الخدمات الخارجية، مما يساعد في تجنب حدود المعدل وتحسين الأداء. + + + + يتيح المدخل البشري للوكلاء طلب معلومات إضافية أو توضيحات عند الحاجة. هذه الميزة ضرورية في عمليات صنع القرار المعقدة أو عندما يحتاج الوكلاء إلى مزيد من التفاصيل لإكمال مهمة بفعالية. + + لدمج المدخل البشري في تنفيذ الوكيل، عيّن علامة `human_input` في تعريف المهمة. عند التفعيل، يطلب الوكيل من المستخدم إدخالًا قبل تقديم إجابته النهائية. يمكن أن يوفر هذا الإدخال سياقًا إضافيًا أو يوضح الغموض أو يتحقق من مخرجات الوكيل. + + للحصول على إرشادات تنفيذ مفصلة، راجع [دليل الإنسان في الحلقة](/ar/enterprise/guides/human-in-the-loop). + + + + يوفر CrewAI مجموعة من خيارات التخصيص المتقدمة: + + - **تخصيص نموذج اللغة**: يمكن تخصيص الوكلاء بنماذج لغوية محددة (`llm`) ونماذج لغوية لاستدعاء الدوال (`function_calling_llm`) + - **إعدادات الأداء والتصحيح**: ضبط أداء الوكيل ومراقبة عملياته + - **الوضع المفصل**: يتيح تسجيلًا مفصلًا لإجراءات الوكيل، مفيد للتصحيح والتحسين + - **حد RPM**: يحدد العدد الأقصى للطلبات في الدقيقة (`max_rpm`) + - **الحد الأقصى للتكرارات**: تسمح خاصية `max_iter` للمستخدمين بتحديد العدد الأقصى للتكرارات التي يمكن للوكيل تنفيذها لمهمة واحدة + - **التفويض والاستقلالية**: التحكم في قدرة الوكيل على التفويض أو طرح الأسئلة عبر خاصية `allow_delegation` (الافتراضي: True) + - **دمج المدخل البشري**: يمكن للوكلاء طلب معلومات إضافية أو توضيحات عند الحاجة + + + + يكون المدخل البشري مفيدًا بشكل خاص عندما: + - **يحتاج الوكلاء إلى معلومات إضافية أو توضيحات**: عندما يواجه الوكلاء غموضًا أو بيانات غير مكتملة + - **يحتاج الوكلاء إلى اتخاذ قرارات معقدة أو حساسة**: يمكن للمدخل البشري المساعدة في صنع القرارات الأخلاقية أو الدقيقة + - **الإشراف والتحقق من مخرجات الوكيل**: يمكن للمدخل البشري المساعدة في التحقق من النتائج ومنع الأخطاء + - **تخصيص سلوك الوكيل**: يمكن للمدخل البشري توفير ملاحظات لتحسين استجابات الوكيل بمرور الوقت + - **تحديد وحل الأخطاء أو القيود**: يساعد المدخل البشري في معالجة فجوات قدرات الوكيل + + + + أنواع الذاكرة المختلفة المتاحة في CrewAI هي: + - **الذاكرة قصيرة المدى**: تخزين مؤقت للسياق الفوري + - **الذاكرة طويلة المدى**: تخزين دائم للأنماط والمعلومات المكتسبة + - **ذاكرة الكيانات**: تخزين مركز على كيانات محددة وخصائصها + - **الذاكرة السياقية**: ذاكرة تحافظ على السياق عبر التفاعلات + + تعرف على المزيد حول أنواع الذاكرة المختلفة: + ذاكرة CrewAI + + + + لاستخدام Output Pydantic في مهمة، تحتاج إلى تعريف المخرج المتوقع للمهمة كنموذج Pydantic. إليك مثال سريع: + + + + ```python + from pydantic import BaseModel + + class User(BaseModel): + name: str + age: int + ``` + + + + ```python + from crewai import Task, Crew, Agent + from my_models import User + + task = Task( + description="Create a user with the provided name and age", + expected_output=User, # This is the Pydantic model + agent=agent, + tools=[tool1, tool2] + ) + ``` + + + + ```python + from crewai import Agent + from my_models import User + + agent = Agent( + role='User Creator', + goal='Create users', + backstory='I am skilled in creating user accounts', + tools=[tool1, tool2], + output_pydantic=User + ) + ``` + + + + إليك درسًا تعليميًا حول كيفية الحصول على مخرجات منظمة بشكل متسق من وكلائك: + + + + + يمكنك إنشاء أدوات مخصصة عن طريق إنشاء فئة فرعية من فئة `BaseTool` المقدمة من CrewAI أو باستخدام مُزخرف الأداة (tool decorator). ينطوي إنشاء الفئة الفرعية على تعريف فئة جديدة ترث من `BaseTool`، مع تحديد الاسم والوصف وطريقة `_run` للمنطق التشغيلي. يتيح لك مُزخرف الأداة إنشاء كائن `Tool` مباشرة مع الخصائص المطلوبة والمنطق الوظيفي. + + دليل أدوات CrewAI + + + + تحدد خاصية `max_rpm` العدد الأقصى للطلبات في الدقيقة التي يمكن للطاقم تنفيذها لتجنب حدود المعدل، وستتجاوز إعدادات `max_rpm` الفردية للوكلاء إذا قمت بتعيينها. + + + diff --git a/docs/ar/examples/cookbooks.mdx b/docs/ar/examples/cookbooks.mdx new file mode 100644 index 000000000..49280d73c --- /dev/null +++ b/docs/ar/examples/cookbooks.mdx @@ -0,0 +1,49 @@ +--- +title: كتب وصفات CrewAI +description: بدايات سريعة ودفاتر ملاحظات مركّزة على الميزات لتعلم الأنماط بسرعة. +icon: book +mode: "wide" +--- + +## بدايات سريعة وعروض توضيحية + + + + تنسيق عدة Agents على مهام مشتركة. يتضمن دفتر ملاحظات بنمط تعاون شامل. + + + + تعليم الـ Agents التفكير في خطط متعددة المراحل قبل التنفيذ باستخدام أدوات التخطيط. + + + + استكشاف حلقات التأمل الذاتي، ومطالبات النقد، وأنماط التفكير المنظم. + + + + + + تطبيق حواجز حماية على مستوى المهام مع إعادة المحاولة ودوال التحقق والبدائل الآمنة. + + + + ربط CrewAI بـ Gemini مع تأريض البحث للحصول على مخرجات واقعية غنية بالاستشهادات. + + + + إنشاء ملخصات فيديو باستخدام نموذج Gemini متعدد الوسائط وتنسيق CrewAI. + + + + + + عرض جميع دفاتر الملاحظات والعروض التوضيحية التي تستعرض إمكانيات CrewAI المحددة. + + + هل يفتقد نمط معين؟ أرسل طلبًا في منتدى المجتمع وسنوسّع المكتبة. + + + + +استخدم كتب الوصفات لتعلم نمط بسرعة، ثم انتقل إلى الأمثلة الكاملة للتطبيقات الجاهزة للإنتاج. + diff --git a/docs/ar/examples/example.mdx b/docs/ar/examples/example.mdx new file mode 100644 index 000000000..0987e8dff --- /dev/null +++ b/docs/ar/examples/example.mdx @@ -0,0 +1,86 @@ +--- +title: أمثلة CrewAI +description: استكشف أمثلة منسّقة مرتبة حسب Crews وFlows والتكاملات ودفاتر الملاحظات. +icon: rocket-launch +mode: "wide" +--- + +## Crews + + + + تخطيط حملات تسويقية متعددة الـ Agents. + + + تخطيط رحلات مفاجئة مخصصة. + + + مطابقة السيرة الذاتية بالوظائف باستخدام البحث المتجهي. + + + إنشاء أوصاف وظيفية آلية. + + + فريق متعدد الـ Agents يصمم ويبني ألعاب Python. + + + استقطاب المرشحين وتقييمهم. + + + عرض القائمة الكاملة لأمثلة الـ Crews. + + + +## Flows + + + + إنشاء محتوى متعدد الـ Crews مع التوجيه. + + + مراقبة البريد الإلكتروني والرد الآلي. + + + تأهيل العملاء المحتملين مع تدخل بشري. + + + معالجة الملاحظات مع التكاملات. + + + سير عمل التحسين الذاتي التكراري. + + + إنشاء الفصول بالتوازي. + + + عرض القائمة الكاملة لأمثلة الـ Flows. + + + +## التكاملات + + + + التكامل مع إطار عمل LangGraph. + + + استخدام CrewAI مع Azure OpenAI. + + + تكاملات منظومة NVIDIA. + + + عرض جميع أمثلة التكاملات. + + + +## دفاتر الملاحظات + + + + Simple QA Crew + Flow. + + + أمثلة تفاعلية للتعلم والتجريب. + + diff --git a/docs/ar/guides/advanced/customizing-prompts.mdx b/docs/ar/guides/advanced/customizing-prompts.mdx new file mode 100644 index 000000000..c760f828c --- /dev/null +++ b/docs/ar/guides/advanced/customizing-prompts.mdx @@ -0,0 +1,317 @@ +--- +title: تخصيص المطالبات +description: تعمّق في تخصيص المطالبات على المستوى المنخفض في CrewAI، مما يتيح حالات استخدام مخصصة ومعقدة لنماذج ولغات مختلفة. +icon: message-pen +mode: "wide" +--- + +## لماذا نخصص المطالبات؟ + +على الرغم من أن مطالبات CrewAI الافتراضية تعمل بشكل جيد في كثير من السيناريوهات، إلا أن التخصيص على المستوى المنخفض يفتح الباب أمام سلوك أكثر مرونة وقوة للـ Agent. إليك لماذا قد ترغب في الاستفادة من هذا التحكم العميق: + +1. **التحسين لنماذج LLM محددة** – تزدهر النماذج المختلفة (مثل GPT-4 وClaude وLlama) مع تنسيقات مطالبات مصممة لبنيتها الفريدة. +2. **تغيير اللغة** – بناء Agents تعمل حصريًا بلغات غير الإنجليزية مع التعامل مع الفروق الدقيقة بدقة. +3. **التخصص في مجالات معقدة** – تكييف المطالبات لصناعات متخصصة للغاية مثل الرعاية الصحية والمالية والقانون. +4. **ضبط النبرة والأسلوب** – جعل الـ Agents أكثر رسمية أو عفوية أو إبداعية أو تحليلية. +5. **دعم حالات استخدام مخصصة للغاية** – استخدام هياكل وتنسيقات مطالبات متقدمة لتلبية متطلبات معقدة خاصة بالمشروع. + +يستكشف هذا الدليل كيفية الوصول إلى مطالبات CrewAI على مستوى أعمق، مما يمنحك تحكمًا دقيقًا في كيفية تفكير الـ Agents وتفاعلها. + +## فهم نظام المطالبات في CrewAI + +تحت الغطاء، يستخدم CrewAI نظام مطالبات معياري يمكنك تخصيصه على نطاق واسع: + +- **قوالب الـ Agent** – تحكم في نهج كل Agent تجاه دوره المعيّن. +- **شرائح المطالبات** – تتحكم في السلوكيات المتخصصة مثل المهام واستخدام الأدوات وهيكل المخرجات. +- **معالجة الأخطاء** – توجيه كيفية استجابة الـ Agents للإخفاقات والاستثناءات وحالات انتهاء المهلة. +- **مطالبات خاصة بالأدوات** – تعريف تعليمات مفصلة لكيفية استدعاء الأدوات أو استخدامها. + +اطلع على [قوالب المطالبات الأصلية في مستودع CrewAI](https://github.com/crewAIInc/crewAI/blob/main/src/crewai/translations/en.json) لمعرفة كيفية تنظيم هذه العناصر. من هناك، يمكنك تجاوزها أو تكييفها حسب الحاجة لفتح سلوكيات متقدمة. + +## فهم تعليمات النظام الافتراضية + + +**مشكلة شفافية الإنتاج**: يحقن CrewAI تلقائيًا تعليمات افتراضية في مطالباتك قد لا تكون على علم بها. يشرح هذا القسم ما يحدث تحت الغطاء وكيفية الحصول على تحكم كامل. + + +عندما تعرّف Agent بـ `role` و`goal` و`backstory`، يضيف CrewAI تلقائيًا تعليمات نظام إضافية تتحكم في التنسيق والسلوك. فهم هذه الحقن الافتراضية أمر بالغ الأهمية لأنظمة الإنتاج التي تحتاج شفافية كاملة في المطالبات. + +### ما يحقنه CrewAI تلقائيًا + +بناءً على تهيئة الـ Agent، يضيف CrewAI تعليمات افتراضية مختلفة: + +#### للـ Agents بدون أدوات +```text +"I MUST use these formats, my job depends on it!" +``` + +#### للـ Agents مع أدوات +```text +"IMPORTANT: Use the following format in your response: + +Thought: you should always think about what to do +Action: the action to take, only one name of [tool_names] +Action Input: the input to the action, just a simple JSON object... +``` + +#### للمخرجات المنظمة (JSON/Pydantic) +```text +"Ensure your final answer contains only the content in the following format: {output_format} +Ensure the final output does not include any code block markers like ```json or ```python." +``` + +### عرض مطالبة النظام الكاملة + +لمعرفة المطالبة المرسلة بالضبط إلى LLM، يمكنك فحص المطالبة المولّدة: + +```python +from crewai import Agent, Crew, Task +from crewai.utilities.prompts import Prompts + +# Create your agent +agent = Agent( + role="Data Analyst", + goal="Analyze data and provide insights", + backstory="You are an expert data analyst with 10 years of experience.", + verbose=True +) + +# Create a sample task +task = Task( + description="Analyze the sales data and identify trends", + expected_output="A detailed analysis with key insights and trends", + agent=agent +) + +# Create the prompt generator +prompt_generator = Prompts( + agent=agent, + has_tools=len(agent.tools) > 0, + use_system_prompt=agent.use_system_prompt +) + +# Generate and inspect the actual prompt +generated_prompt = prompt_generator.task_execution() + +# Print the complete system prompt that will be sent to the LLM +if "system" in generated_prompt: + print("=== SYSTEM PROMPT ===") + print(generated_prompt["system"]) + print("\n=== USER PROMPT ===") + print(generated_prompt["user"]) +else: + print("=== COMPLETE PROMPT ===") + print(generated_prompt["prompt"]) + +# You can also see how the task description gets formatted +print("\n=== TASK CONTEXT ===") +print(f"Task Description: {task.description}") +print(f"Expected Output: {task.expected_output}") +``` + +### تجاوز التعليمات الافتراضية + +لديك عدة خيارات للحصول على تحكم كامل في المطالبات: + +#### الخيار 1: القوالب المخصصة (مُوصى به) +```python +from crewai import Agent + +# Define your own system template without default instructions +custom_system_template = """You are {role}. {backstory} +Your goal is: {goal} + +Respond naturally and conversationally. Focus on providing helpful, accurate information.""" + +custom_prompt_template = """Task: {input} + +Please complete this task thoughtfully.""" + +agent = Agent( + role="Research Assistant", + goal="Help users find accurate information", + backstory="You are a helpful research assistant.", + system_template=custom_system_template, + prompt_template=custom_prompt_template, + use_system_prompt=True # Use separate system/user messages +) +``` + +#### الخيار 2: ملف مطالبات مخصص +أنشئ ملف `custom_prompts.json` لتجاوز شرائح مطالبات محددة: + +```json +{ + "slices": { + "no_tools": "\nProvide your best answer in a natural, conversational way.", + "tools": "\nYou have access to these tools: {tools}\n\nUse them when helpful, but respond naturally.", + "formatted_task_instructions": "Format your response as: {output_format}" + } +} +``` + +ثم استخدمه في Crew: + +```python +crew = Crew( + agents=[agent], + tasks=[task], + prompt_file="custom_prompts.json", + verbose=True +) +``` + +#### الخيار 3: تعطيل مطالبات النظام لنماذج o1 +```python +agent = Agent( + role="Analyst", + goal="Analyze data", + backstory="Expert analyst", + use_system_prompt=False # Disables system prompt separation +) +``` + +### التصحيح باستخدام أدوات المراقبة + +لشفافية الإنتاج، استخدم منصات المراقبة لمتابعة جميع المطالبات وتفاعلات LLM. يتيح لك ذلك رؤية المطالبات المرسلة بالضبط (بما في ذلك التعليمات الافتراضية) إلى نماذج LLM. + +راجع [توثيق المراقبة](/ar/observability/overview) للحصول على أدلة تكامل مفصلة مع منصات متعددة بما في ذلك Langfuse وMLflow وWeights & Biases وحلول التسجيل المخصصة. + +### أفضل الممارسات للإنتاج + +1. **افحص المطالبات المولّدة دائمًا** قبل النشر في الإنتاج +2. **استخدم قوالب مخصصة** عندما تحتاج تحكمًا كاملاً في محتوى المطالبات +3. **دمج أدوات المراقبة** للمتابعة المستمرة للمطالبات (راجع [توثيق المراقبة](/ar/observability/overview)) +4. **اختبر مع نماذج LLM مختلفة** حيث قد تعمل التعليمات الافتراضية بشكل مختلف عبر النماذج +5. **وثّق تخصيصات المطالبات** لشفافية الفريق + + +التعليمات الافتراضية موجودة لضمان سلوك Agent متسق، لكنها قد تتعارض مع المتطلبات الخاصة بالمجال. استخدم خيارات التخصيص أعلاه للحفاظ على تحكم كامل في سلوك Agent في أنظمة الإنتاج. + + +## أفضل الممارسات لإدارة ملفات المطالبات + +عند الانخراط في تخصيص المطالبات على المستوى المنخفض، اتبع هذه الإرشادات للحفاظ على التنظيم وسهولة الصيانة: + +1. **احتفظ بالملفات منفصلة** – خزّن المطالبات المخصصة في ملفات JSON مخصصة خارج قاعدة الكود الرئيسية. +2. **التحكم في الإصدارات** – تتبع التغييرات داخل المستودع مع ضمان توثيق واضح لتعديلات المطالبات بمرور الوقت. +3. **التنظيم حسب النموذج أو اللغة** – استخدم تسميات مثل `prompts_llama.json` أو `prompts_es.json` لتحديد التهيئات المتخصصة بسرعة. +4. **توثيق التغييرات** – قدم تعليقات أو حافظ على ملف يوضح غرض ونطاق تخصيصاتك. +5. **قلل التعديلات** – تجاوز فقط الشرائح المحددة التي تحتاج حقًا لتعديلها مع الحفاظ على الوظائف الافتراضية لكل شيء آخر. + +## أبسط طريقة لتخصيص المطالبات + +إحدى الطرق المباشرة هي إنشاء ملف JSON للمطالبات التي تريد تجاوزها ثم توجيه Crew إلى ذلك الملف: + +1. أنشئ ملف JSON بشرائح المطالبات المحدّثة. +2. أشر إلى ذلك الملف عبر معامل `prompt_file` في Crew. + +يدمج CrewAI بعد ذلك تخصيصاتك مع الإعدادات الافتراضية، فلا تحتاج لإعادة تعريف كل مطالبة. إليك الطريقة: + +### مثال: تخصيص أساسي للمطالبات + +أنشئ ملف `custom_prompts.json` بالمطالبات التي تريد تعديلها. تأكد من إدراج جميع المطالبات عالية المستوى التي يجب أن يحتويها، وليس فقط تغييراتك: + +```json +{ + "slices": { + "format": "When responding, follow this structure:\n\nTHOUGHTS: Your step-by-step thinking\nACTION: Any tool you're using\nRESULT: Your final answer or conclusion" + } +} +``` + +ثم ادمجه هكذا: + +```python +from crewai import Agent, Crew, Task, Process + +# Create agents and tasks as normal +researcher = Agent( + role="Research Specialist", + goal="Find information on quantum computing", + backstory="You are a quantum physics expert", + verbose=True +) + +research_task = Task( + description="Research quantum computing applications", + expected_output="A summary of practical applications", + agent=researcher +) + +# Create a crew with your custom prompt file +crew = Crew( + agents=[researcher], + tasks=[research_task], + prompt_file="path/to/custom_prompts.json", + verbose=True +) + +# Run the crew +result = crew.kickoff() +``` + +بهذه التعديلات البسيطة، تحصل على تحكم منخفض المستوى في كيفية تواصل الـ Agents وحل المهام. + +## التحسين لنماذج محددة + +تزدهر النماذج المختلفة مع مطالبات منظمة بطرق مختلفة. إجراء تعديلات أعمق يمكن أن يعزز الأداء بشكل كبير من خلال مواءمة مطالباتك مع خصائص النموذج. + +### مثال: قالب مطالبات Llama 3.3 + +على سبيل المثال، عند التعامل مع Llama 3.3 من Meta، قد يعكس التخصيص على المستوى الأعمق الهيكل الموصى به الموضح في: +https://www.llama.com/docs/model-cards-and-prompt-formats/llama3_1/#prompt-template + +إليك مثالاً يوضح كيف يمكنك ضبط Agent للاستفادة من Llama 3.3 في الكود: + +```python +from crewai import Agent, Crew, Task, Process +from crewai_tools import DirectoryReadTool, FileReadTool + +# Define templates for system, user (prompt), and assistant (response) messages +system_template = """<|begin_of_text|><|start_header_id|>system<|end_header_id|>{{ .System }}<|eot_id|>""" +prompt_template = """<|start_header_id|>user<|end_header_id|>{{ .Prompt }}<|eot_id|>""" +response_template = """<|start_header_id|>assistant<|end_header_id|>{{ .Response }}<|eot_id|>""" + +# Create an Agent using Llama-specific layouts +principal_engineer = Agent( + role="Principal Engineer", + goal="Oversee AI architecture and make high-level decisions", + backstory="You are the lead engineer responsible for critical AI systems", + verbose=True, + llm="groq/llama-3.3-70b-versatile", # Using the Llama 3 model + system_template=system_template, + prompt_template=prompt_template, + response_template=response_template, + tools=[DirectoryReadTool(), FileReadTool()] +) + +# Define a sample task +engineering_task = Task( + description="Review AI implementation files for potential improvements", + expected_output="A summary of key findings and recommendations", + agent=principal_engineer +) + +# Create a Crew for the task +llama_crew = Crew( + agents=[principal_engineer], + tasks=[engineering_task], + process=Process.sequential, + verbose=True +) + +# Execute the crew +result = llama_crew.kickoff() +print(result.raw) +``` + +من خلال هذه التهيئة العميقة، يمكنك ممارسة تحكم شامل منخفض المستوى في سير العمل القائمة على Llama دون الحاجة إلى ملف JSON منفصل. + +## الخلاصة + +يفتح تخصيص المطالبات على المستوى المنخفض في CrewAI الباب أمام حالات استخدام مخصصة ومعقدة للغاية. من خلال إنشاء ملفات مطالبات منظمة (أو قوالب مضمّنة مباشرة)، يمكنك استيعاب نماذج ولغات ومجالات متخصصة متنوعة. يضمن هذا المستوى من المرونة أنك تستطيع صياغة سلوك الذكاء الاصطناعي الذي تحتاجه بالضبط، مع العلم أن CrewAI لا يزال يوفر إعدادات افتراضية موثوقة عندما لا تتجاوزها. + + +لديك الآن الأساس لتخصيصات المطالبات المتقدمة في CrewAI. سواء كنت تتكيف مع هياكل خاصة بالنموذج أو قيود خاصة بالمجال، يتيح لك هذا النهج المنخفض المستوى تشكيل تفاعلات الـ Agent بطرق متخصصة للغاية. + diff --git a/docs/ar/guides/advanced/fingerprinting.mdx b/docs/ar/guides/advanced/fingerprinting.mdx new file mode 100644 index 000000000..12599a88f --- /dev/null +++ b/docs/ar/guides/advanced/fingerprinting.mdx @@ -0,0 +1,134 @@ +--- +title: البصمات الرقمية +description: تعلم كيفية استخدام نظام البصمات الرقمية في CrewAI لتحديد وتتبع المكونات بشكل فريد طوال دورة حياتها. +icon: fingerprint +mode: "wide" +--- + +## نظرة عامة + +توفر البصمات الرقمية في CrewAI طريقة لتحديد وتتبع المكونات بشكل فريد طوال دورة حياتها. يتلقى كل `Agent` و`Crew` و`Task` بصمة رقمية فريدة تلقائيًا عند الإنشاء، ولا يمكن تجاوزها يدويًا. + +يمكن استخدام هذه البصمات لـ: +- تدقيق وتتبع استخدام المكونات +- ضمان سلامة هوية المكونات +- إرفاق بيانات وصفية بالمكونات +- إنشاء سلسلة عمليات قابلة للتتبع + +## كيف تعمل البصمات الرقمية + +البصمة الرقمية هي نسخة من فئة `Fingerprint` من وحدة `crewai.security`. تحتوي كل بصمة على: + +- سلسلة UUID: معرّف فريد للمكون يتم إنشاؤه تلقائيًا ولا يمكن تعيينه يدويًا +- طابع زمني للإنشاء: متى تم إنشاء البصمة، يُعيَّن تلقائيًا ولا يمكن تعديله يدويًا +- بيانات وصفية: قاموس معلومات إضافية يمكن تخصيصه + +تُنشأ البصمات الرقمية وتُعيَّن تلقائيًا عند إنشاء المكون. يكشف كل مكون بصمته من خلال خاصية للقراءة فقط. + +## الاستخدام الأساسي + +### الوصول إلى البصمات الرقمية + +```python +from crewai import Agent, Crew, Task + +# Create components - fingerprints are automatically generated +agent = Agent( + role="Data Scientist", + goal="Analyze data", + backstory="Expert in data analysis" +) + +crew = Crew( + agents=[agent], + tasks=[] +) + +task = Task( + description="Analyze customer data", + expected_output="Insights from data analysis", + agent=agent +) + +# Access the fingerprints +agent_fingerprint = agent.fingerprint +crew_fingerprint = crew.fingerprint +task_fingerprint = task.fingerprint + +# Print the UUID strings +print(f"Agent fingerprint: {agent_fingerprint.uuid_str}") +print(f"Crew fingerprint: {crew_fingerprint.uuid_str}") +print(f"Task fingerprint: {task_fingerprint.uuid_str}") +``` + +### العمل مع البيانات الوصفية للبصمة + +يمكنك إضافة بيانات وصفية إلى البصمات لسياق إضافي: + +```python +# Add metadata to the agent's fingerprint +agent.security_config.fingerprint.metadata = { + "version": "1.0", + "department": "Data Science", + "project": "Customer Analysis" +} + +# Access the metadata +print(f"Agent metadata: {agent.fingerprint.metadata}") +``` + +## استمرارية البصمة + +صُممت البصمات لتبقى ثابتة دون تغيير طوال دورة حياة المكون. إذا عدّلت مكونًا، تظل البصمة كما هي: + +```python +original_fingerprint = agent.fingerprint.uuid_str + +# Modify the agent +agent.goal = "New goal for analysis" + +# The fingerprint remains unchanged +assert agent.fingerprint.uuid_str == original_fingerprint +``` + +## البصمات الحتمية + +بينما لا يمكنك تعيين UUID والطابع الزمني مباشرة، يمكنك إنشاء بصمات حتمية باستخدام طريقة `generate` مع بذرة: + +```python +from crewai.security import Fingerprint + +# Create a deterministic fingerprint using a seed string +deterministic_fingerprint = Fingerprint.generate(seed="my-agent-id") + +# The same seed always produces the same fingerprint +same_fingerprint = Fingerprint.generate(seed="my-agent-id") +assert deterministic_fingerprint.uuid_str == same_fingerprint.uuid_str + +# You can also set metadata +custom_fingerprint = Fingerprint.generate( + seed="my-agent-id", + metadata={"version": "1.0"} +) +``` + +## الاستخدام المتقدم + +### هيكل البصمة + +لكل بصمة الهيكل التالي: + +```python +from crewai.security import Fingerprint + +fingerprint = agent.fingerprint + +# UUID string - the unique identifier (auto-generated) +uuid_str = fingerprint.uuid_str # e.g., "123e4567-e89b-12d3-a456-426614174000" + +# Creation timestamp (auto-generated) +created_at = fingerprint.created_at # A datetime object + +# Metadata - for additional information (can be customized) +metadata = fingerprint.metadata # A dictionary, defaults to {} +``` diff --git a/docs/ar/guides/agents/crafting-effective-agents.mdx b/docs/ar/guides/agents/crafting-effective-agents.mdx new file mode 100644 index 000000000..c1c6b1db3 --- /dev/null +++ b/docs/ar/guides/agents/crafting-effective-agents.mdx @@ -0,0 +1,453 @@ +--- +title: صياغة Agents فعّالة +description: تعلم أفضل الممارسات لتصميم Agents ذكاء اصطناعي قوية ومتخصصة تتعاون بفعالية لحل المشكلات المعقدة. +icon: robot +mode: "wide" +--- + +## فن وعلم تصميم الـ Agent + +في قلب CrewAI يكمن الـ Agent - كيان ذكاء اصطناعي متخصص مصمم لأداء أدوار محددة ضمن إطار تعاوني. بينما إنشاء Agents أساسية أمر بسيط، فإن صياغة Agents فعّالة حقًا تنتج نتائج استثنائية يتطلب فهم مبادئ التصميم الأساسية وأفضل الممارسات. + +سيساعدك هذا الدليل على إتقان فن تصميم الـ Agent، مما يمكّنك من إنشاء شخصيات AI متخصصة تتعاون بفعالية وتفكر بشكل نقدي وتنتج مخرجات عالية الجودة مصممة لاحتياجاتك المحددة. + +### لماذا يهم تصميم الـ Agent + +الطريقة التي تعرّف بها الـ Agents تؤثر بشكل كبير على: + +1. **جودة المخرجات**: الـ Agents المصممة جيدًا تنتج نتائج أكثر صلة وجودة +2. **فعالية التعاون**: الـ Agents ذات المهارات المكملة تعمل معًا بكفاءة أكبر +3. **أداء المهام**: الـ Agents ذات الأدوار والأهداف الواضحة تنفذ المهام بفعالية أكبر +4. **قابلية التوسع**: الـ Agents المصممة بعناية يمكن إعادة استخدامها عبر Crews وسياقات متعددة + +لنستكشف أفضل الممارسات لإنشاء Agents تتفوق في هذه الأبعاد. + +## قاعدة 80/20: ركّز على المهام أكثر من الـ Agents + +عند بناء أنظمة AI فعّالة، تذكر هذا المبدأ الحاسم: **80% من جهدك يجب أن يذهب لتصميم المهام، و20% فقط لتعريف الـ Agents**. + +لماذا؟ لأن حتى أفضل Agent معرّف سيفشل مع مهام مصممة بشكل سيئ، لكن المهام المصممة جيدًا يمكنها رفع مستوى حتى Agent بسيط. هذا يعني: + +- اقضِ معظم وقتك في كتابة تعليمات مهام واضحة +- حدد المدخلات والمخرجات المتوقعة بالتفصيل +- أضف أمثلة وسياقًا لتوجيه التنفيذ +- خصص الوقت المتبقي لدور Agent وهدفه وخلفيته + +هذا لا يعني أن تصميم الـ Agent ليس مهمًا - بل هو مهم بالتأكيد. لكن تصميم المهام هو حيث تحدث معظم إخفاقات التنفيذ، لذا رتّب أولوياتك وفقًا لذلك. + +## المبادئ الأساسية لتصميم Agent فعّال + +### 1. إطار الدور-الهدف-الخلفية + +أقوى الـ Agents في CrewAI مبنية على أساس قوي من ثلاثة عناصر رئيسية: + +#### الدور: الوظيفة المتخصصة للـ Agent + +يحدد الدور ما يفعله الـ Agent ومجال خبرته. عند صياغة الأدوار: + +- **كن محددًا ومتخصصًا**: بدلاً من "كاتب"، استخدم "متخصص في التوثيق التقني" أو "راوي قصص إبداعي" +- **تماشَ مع المهن الواقعية**: ابنِ الأدوار على نماذج مهنية معروفة +- **تضمين خبرة المجال**: حدد مجال معرفة الـ Agent (مثل "محلل مالي متخصص في اتجاهات السوق") + +**أمثلة على أدوار فعّالة:** +```yaml +role: "Senior UX Researcher specializing in user interview analysis" +role: "Full-Stack Software Architect with expertise in distributed systems" +role: "Corporate Communications Director specializing in crisis management" +``` + +#### الهدف: غرض الـ Agent ودافعه + +يوجه الهدف جهود الـ Agent ويشكّل عملية صنع القرار. الأهداف الفعّالة يجب أن: + +- **تكون واضحة ومركّزة على النتائج**: حدد ما يحاول الـ Agent تحقيقه +- **تؤكد على معايير الجودة**: تضمين توقعات حول جودة العمل +- **تتضمن معايير النجاح**: ساعد الـ Agent على فهم ما يعنيه "الجيد" + +**أمثلة على أهداف فعّالة:** +```yaml +goal: "Uncover actionable user insights by analyzing interview data and identifying recurring patterns, unmet needs, and improvement opportunities" +goal: "Design robust, scalable system architectures that balance performance, maintainability, and cost-effectiveness" +goal: "Craft clear, empathetic crisis communications that address stakeholder concerns while protecting organizational reputation" +``` + +#### الخلفية: تجربة الـ Agent ومنظوره + +تمنح الخلفية عمقًا لشخصية الـ Agent، مؤثرة في كيفية تعامله مع المشكلات وتفاعله مع الآخرين. الخلفيات الجيدة: + +- **تؤسس الخبرة والتجربة**: تشرح كيف اكتسب الـ Agent مهاراته +- **تحدد أسلوب العمل والقيم**: تصف كيف يتعامل الـ Agent مع عمله +- **تنشئ شخصية متماسكة**: تضمن أن جميع عناصر الخلفية تتماشى مع الدور والهدف + +**أمثلة على خلفيات فعّالة:** +```yaml +backstory: "You have spent 15 years conducting and analyzing user research for top tech companies. You have a talent for reading between the lines and identifying patterns that others miss. You believe that good UX is invisible and that the best insights come from listening to what users don't say as much as what they do say." + +backstory: "With 20+ years of experience building distributed systems at scale, you've developed a pragmatic approach to software architecture. You've seen both successful and failed systems and have learned valuable lessons from each. You balance theoretical best practices with practical constraints and always consider the maintenance and operational aspects of your designs." + +backstory: "As a seasoned communications professional who has guided multiple organizations through high-profile crises, you understand the importance of transparency, speed, and empathy in crisis response. You have a methodical approach to crafting messages that address concerns while maintaining organizational credibility." +``` + +### 2. المتخصصون أفضل من العموميين + +يؤدي الـ Agents أداءً أفضل بشكل ملحوظ عند منحهم أدوارًا متخصصة بدلاً من عامة. الـ Agent المركّز بشدة ينتج مخرجات أكثر دقة وصلة: + +**عام (أقل فعالية):** +```yaml +role: "Writer" +``` + +**متخصص (أكثر فعالية):** +```yaml +role: "Technical Blog Writer specializing in explaining complex AI concepts to non-technical audiences" +``` + +**فوائد التخصص:** +- فهم أوضح للمخرجات المتوقعة +- أداء أكثر اتساقًا +- توافق أفضل مع المهام المحددة +- قدرة محسّنة على إصدار أحكام خاصة بالمجال + +### 3. التوازن بين التخصص والمرونة + +الـ Agents الفعّالة تحقق التوازن الصحيح بين التخصص (القيام بشيء واحد بشكل ممتاز) والمرونة (التكيف مع مواقف متنوعة): + +- **تخصص في الدور، مرونة في التطبيق**: أنشئ Agents بمهارات متخصصة يمكن تطبيقها عبر سياقات متعددة +- **تجنب التعريفات الضيقة جدًا**: تأكد من أن الـ Agents يمكنها التعامل مع التنوعات ضمن مجال خبرتها +- **ضع في الاعتبار السياق التعاوني**: صمم Agents تكمّل تخصصاتها الـ Agents الأخرى التي ستعمل معها + +### 4. تعيين مستويات الخبرة المناسبة + +مستوى الخبرة الذي تعيّنه للـ Agent يشكّل كيفية تعامله مع المهام: + +- **Agents مبتدئة**: جيدة للمهام المباشرة والعصف الذهني والمسودات الأولية +- **Agents متوسطة**: مناسبة لمعظم المهام القياسية مع تنفيذ موثوق +- **Agents خبيرة**: الأفضل للمهام المعقدة والمتخصصة التي تتطلب عمقًا ودقة +- **Agents على مستوى عالمي**: محجوزة للمهام الحرجة حيث الجودة الاستثنائية مطلوبة + +اختر مستوى الخبرة المناسب بناءً على تعقيد المهمة ومتطلبات الجودة. لمعظم Crews التعاونية، غالبًا ما يعمل مزيج من مستويات الخبرة بشكل أفضل، مع تعيين خبرة أعلى للوظائف المتخصصة الأساسية. + +## أمثلة عملية: قبل وبعد + +لنلقِ نظرة على بعض أمثلة تعريفات الـ Agent قبل وبعد تطبيق أفضل الممارسات: + +### مثال 1: Agent إنشاء المحتوى + +**قبل:** +```yaml +role: "Writer" +goal: "Write good content" +backstory: "You are a writer who creates content for websites." +``` + +**بعد:** +```yaml +role: "B2B Technology Content Strategist" +goal: "Create compelling, technically accurate content that explains complex topics in accessible language while driving reader engagement and supporting business objectives" +backstory: "You have spent a decade creating content for leading technology companies, specializing in translating technical concepts for business audiences. You excel at research, interviewing subject matter experts, and structuring information for maximum clarity and impact. You believe that the best B2B content educates first and sells second, building trust through genuine expertise rather than marketing hype." +``` + +### مثال 2: Agent البحث + +**قبل:** +```yaml +role: "Researcher" +goal: "Find information" +backstory: "You are good at finding information online." +``` + +**بعد:** +```yaml +role: "Academic Research Specialist in Emerging Technologies" +goal: "Discover and synthesize cutting-edge research, identifying key trends, methodologies, and findings while evaluating the quality and reliability of sources" +backstory: "With a background in both computer science and library science, you've mastered the art of digital research. You've worked with research teams at prestigious universities and know how to navigate academic databases, evaluate research quality, and synthesize findings across disciplines. You're methodical in your approach, always cross-referencing information and tracing claims to primary sources before drawing conclusions." +``` + +## صياغة مهام فعّالة للـ Agents + +بينما تصميم الـ Agent مهم، تصميم المهام حاسم للتنفيذ الناجح. إليك أفضل الممارسات لتصميم مهام تهيئ الـ Agents للنجاح: + +### تشريح المهمة الفعّالة + +المهمة المصممة جيدًا لها مكونان رئيسيان يخدمان أغراضًا مختلفة: + +#### وصف المهمة: العملية +يجب أن يركز الوصف على ماذا تفعل وكيف تفعله، بما في ذلك: +- تعليمات مفصلة للتنفيذ +- سياق ومعلومات خلفية +- النطاق والقيود +- خطوات العملية المتبعة + +#### المخرجات المتوقعة: التسليم +يجب أن تحدد المخرجات المتوقعة شكل النتيجة النهائية: +- مواصفات التنسيق (markdown، JSON، إلخ) +- متطلبات الهيكل +- معايير الجودة +- أمثلة على مخرجات جيدة (عند الإمكان) + +### أفضل ممارسات تصميم المهام + +#### 1. غرض واحد، مخرج واحد +تؤدي المهام أفضل أداء عند التركيز على هدف واضح واحد: + +**مثال سيئ (واسع جدًا):** +```yaml +task_description: "Research market trends, analyze the data, and create a visualization." +``` + +**مثال جيد (مركّز):** +```yaml +# Task 1 +research_task: + description: "Research the top 5 market trends in the AI industry for 2024." + expected_output: "A markdown list of the 5 trends with supporting evidence." + +# Task 2 +analysis_task: + description: "Analyze the identified trends to determine potential business impacts." + expected_output: "A structured analysis with impact ratings (High/Medium/Low)." + +# Task 3 +visualization_task: + description: "Create a visual representation of the analyzed trends." + expected_output: "A description of a chart showing trends and their impact ratings." +``` + +#### 2. كن صريحًا بشأن المدخلات والمخرجات +حدد دائمًا بوضوح ما المدخلات التي ستستخدمها المهمة وكيف يجب أن تبدو المخرجات: + +**مثال:** +```yaml +analysis_task: + description: > + Analyze the customer feedback data from the CSV file. + Focus on identifying recurring themes related to product usability. + Consider sentiment and frequency when determining importance. + expected_output: > + A markdown report with the following sections: + 1. Executive summary (3-5 bullet points) + 2. Top 3 usability issues with supporting data + 3. Recommendations for improvement +``` + +#### 3. تضمين الغرض والسياق +اشرح لماذا تهم المهمة وكيف تتناسب مع سير العمل الأكبر: + +**مثال:** +```yaml +competitor_analysis_task: + description: > + Analyze our three main competitors' pricing strategies. + This analysis will inform our upcoming pricing model revision. + Focus on identifying patterns in how they price premium features + and how they structure their tiered offerings. +``` + +#### 4. استخدام أدوات المخرجات المنظمة +للمخرجات القابلة للقراءة آليًا، حدد التنسيق بوضوح: + +**مثال:** +```yaml +data_extraction_task: + description: "Extract key metrics from the quarterly report." + expected_output: "JSON object with the following keys: revenue, growth_rate, customer_acquisition_cost, and retention_rate." +``` + +## أخطاء شائعة يجب تجنبها + +بناءً على الدروس المستفادة من التطبيقات الواقعية، إليك أكثر المزالق شيوعًا في تصميم الـ Agent والمهام: + +### 1. تعليمات مهام غير واضحة + +**المشكلة:** تفتقر المهام لتفاصيل كافية مما يصعّب على الـ Agents تنفيذها بفعالية. + +**مثال تصميم سيئ:** +```yaml +research_task: + description: "Research AI trends." + expected_output: "A report on AI trends." +``` + +**نسخة محسّنة:** +```yaml +research_task: + description: > + Research the top emerging AI trends for 2024 with a focus on: + 1. Enterprise adoption patterns + 2. Technical breakthroughs in the past 6 months + 3. Regulatory developments affecting implementation + + For each trend, identify key companies, technologies, and potential business impacts. + expected_output: > + A comprehensive markdown report with: + - Executive summary (5 bullet points) + - 5-7 major trends with supporting evidence + - For each trend: definition, examples, and business implications + - References to authoritative sources +``` + +### 2. "مهام إلهية" تحاول فعل الكثير + +**المشكلة:** مهام تجمع عمليات معقدة متعددة في مجموعة تعليمات واحدة. + +**مثال تصميم سيئ:** +```yaml +comprehensive_task: + description: "Research market trends, analyze competitor strategies, create a marketing plan, and design a launch timeline." +``` + +**نسخة محسّنة:** +قسّمها إلى مهام متسلسلة ومركّزة: +```yaml +# Task 1: Research +market_research_task: + description: "Research current market trends in the SaaS project management space." + expected_output: "A markdown summary of key market trends." + +# Task 2: Competitive Analysis +competitor_analysis_task: + description: "Analyze strategies of the top 3 competitors based on the market research." + expected_output: "A comparison table of competitor strategies." + context: [market_research_task] + +# Continue with additional focused tasks... +``` + +### 3. عدم توافق الوصف والمخرجات المتوقعة + +**المشكلة:** وصف المهمة يطلب شيئًا بينما المخرجات المتوقعة تحدد شيئًا مختلفًا. + +**مثال تصميم سيئ:** +```yaml +analysis_task: + description: "Analyze customer feedback to find areas of improvement." + expected_output: "A marketing plan for the next quarter." +``` + +**نسخة محسّنة:** +```yaml +analysis_task: + description: "Analyze customer feedback to identify the top 3 areas for product improvement." + expected_output: "A report listing the 3 priority improvement areas with supporting customer quotes and data points." +``` + +### 4. عدم فهم العملية بنفسك + +**المشكلة:** مطالبة الـ Agents بتنفيذ مهام لا تفهمها أنت بالكامل. + +**الحل:** +1. حاول تنفيذ المهمة يدويًا أولاً +2. وثّق عمليتك ونقاط القرار ومصادر المعلومات +3. استخدم هذا التوثيق كأساس لوصف مهمتك + +### 5. الاستخدام المبكر للهياكل الهرمية + +**المشكلة:** إنشاء هرميات Agents معقدة بلا داعٍ حيث تعمل العمليات المتسلسلة بشكل أفضل. + +**الحل:** ابدأ بالعمليات المتسلسلة وانتقل إلى النماذج الهرمية فقط عندما يتطلب تعقيد سير العمل ذلك حقًا. + +### 6. تعريفات Agent غامضة أو عامة + +**المشكلة:** تعريفات Agent العامة تؤدي لمخرجات عامة. + +**مثال تصميم سيئ:** +```yaml +agent: + role: "Business Analyst" + goal: "Analyze business data" + backstory: "You are good at business analysis." +``` + +**نسخة محسّنة:** +```yaml +agent: + role: "SaaS Metrics Specialist focusing on growth-stage startups" + goal: "Identify actionable insights from business data that can directly impact customer retention and revenue growth" + backstory: "With 10+ years analyzing SaaS business models, you've developed a keen eye for the metrics that truly matter for sustainable growth. You've helped numerous companies identify the leverage points that turned around their business trajectory. You believe in connecting data to specific, actionable recommendations rather than general observations." +``` + +## استراتيجيات متقدمة لتصميم الـ Agent + +### التصميم للتعاون + +عند إنشاء Agents ستعمل معًا في Crew، ضع في اعتبارك: + +- **مهارات مكملة**: صمم Agents بقدرات مميزة ومكملة +- **نقاط التسليم**: حدد واجهات واضحة لكيفية انتقال العمل بين الـ Agents +- **توتر بنّاء**: أحيانًا، إنشاء Agents بمنظورات مختلفة قليلاً يمكن أن يؤدي لنتائج أفضل من خلال حوار منتج + +على سبيل المثال، قد يتضمن Crew إنشاء محتوى: + +```yaml +# Research Agent +role: "Research Specialist for technical topics" +goal: "Gather comprehensive, accurate information from authoritative sources" +backstory: "You are a meticulous researcher with a background in library science..." + +# Writer Agent +role: "Technical Content Writer" +goal: "Transform research into engaging, clear content that educates and informs" +backstory: "You are an experienced writer who excels at explaining complex concepts..." + +# Editor Agent +role: "Content Quality Editor" +goal: "Ensure content is accurate, well-structured, and polished while maintaining consistency" +backstory: "With years of experience in publishing, you have a keen eye for detail..." +``` + +### إنشاء مستخدمي أدوات متخصصين + +يمكن تصميم بعض الـ Agents خصيصًا للاستفادة من أدوات معينة بفعالية: + +```yaml +role: "Data Analysis Specialist" +goal: "Derive meaningful insights from complex datasets through statistical analysis" +backstory: "With a background in data science, you excel at working with structured and unstructured data..." +tools: [PythonREPLTool, DataVisualizationTool, CSVAnalysisTool] +``` + +### تكييف الـ Agents مع قدرات LLM + +للنماذج المختلفة نقاط قوة مختلفة. صمم الـ Agents مع وضع هذه القدرات في الاعتبار: + +```yaml +# For complex reasoning tasks +analyst: + role: "Data Insights Analyst" + goal: "..." + backstory: "..." + llm: openai/gpt-4o + +# For creative content +writer: + role: "Creative Content Writer" + goal: "..." + backstory: "..." + llm: anthropic/claude-3-opus +``` + +## اختبار تصميم الـ Agent والتكرار عليه + +تصميم الـ Agent غالبًا عملية تكرارية. إليك نهجًا عمليًا: + +1. **ابدأ بنموذج أولي**: أنشئ تعريف Agent أولي +2. **اختبر مع مهام نموذجية**: قيّم الأداء على مهام تمثيلية +3. **حلل المخرجات**: حدد نقاط القوة والضعف +4. **صقل التعريف**: اضبط الدور والهدف والخلفية بناءً على الملاحظات +5. **اختبر في بيئة تعاونية**: قيّم كيف يعمل الـ Agent في إعداد Crew + +## الخلاصة + +صياغة Agents فعّالة هي فن وعلم في آن واحد. من خلال تعريف الأدوار والأهداف والخلفيات بعناية بما يتماشى مع احتياجاتك المحددة، ودمجها مع مهام مصممة جيدًا، يمكنك إنشاء متعاونين AI متخصصين ينتجون نتائج استثنائية. + +تذكر أن تصميم الـ Agent والمهام عملية تكرارية. ابدأ بأفضل الممارسات هذه، وراقب الـ Agents أثناء العمل، وصقل نهجك بناءً على ما تتعلمه. وتذكر دائمًا قاعدة 80/20 - ركّز معظم جهدك على إنشاء مهام واضحة ومركّزة للحصول على أفضل النتائج من الـ Agents. + + +تهانينا! أنت الآن تفهم مبادئ وممارسات تصميم Agent الفعّال. طبّق هذه التقنيات لإنشاء Agents قوية ومتخصصة تعمل معًا بسلاسة لإنجاز مهام معقدة. + + +## الخطوات التالية + +- جرّب تهيئات Agent مختلفة لحالة استخدامك المحددة +- تعلم عن [بناء أول Crew](/ar/guides/crews/first-crew) لمعرفة كيف تعمل الـ Agents معًا +- استكشف [CrewAI Flows](/ar/guides/flows/first-flow) لتنسيق أكثر تقدمًا diff --git a/docs/ar/guides/coding-tools/agents-md.mdx b/docs/ar/guides/coding-tools/agents-md.mdx new file mode 100644 index 000000000..e118b72eb --- /dev/null +++ b/docs/ar/guides/coding-tools/agents-md.mdx @@ -0,0 +1,61 @@ +--- +title: أدوات البرمجة +description: استخدم AGENTS.md لتوجيه أدوات البرمجة وبيئات التطوير عبر مشاريع CrewAI. +icon: terminal +mode: "wide" +--- + +## لماذا AGENTS.md + +`AGENTS.md` هو ملف تعليمات خفيف محلي للمستودع يمنح أدوات البرمجة توجيهات متسقة خاصة بالمشروع. ضعه في جذر المشروع واعتبره المصدر الموثوق لكيفية عمل المساعدين: الاصطلاحات والأوامر وملاحظات البنية والحدود. + +## إنشاء مشروع باستخدام CLI + +استخدم CLI الخاص بـ CrewAI لإنشاء هيكل مشروع، وسيُضاف `AGENTS.md` تلقائيًا في الجذر. + +```bash +# Crew +crewai create crew my_crew + +# Flow +crewai create flow my_flow + +# Tool repository +crewai tool create my_tool +``` + +## إعداد الأدوات: توجيه المساعدين إلى AGENTS.md + +### Codex + +يمكن توجيه Codex بملفات `AGENTS.md` الموضوعة في مستودعك. استخدمها لتوفير سياق مشروع مستمر مثل الاصطلاحات والأوامر وتوقعات سير العمل. + +### Claude Code + +يخزّن Claude Code ذاكرة المشروع في `CLAUDE.md`. يمكنك تهيئته بـ `/init` وتحريره باستخدام `/memory`. يدعم Claude Code أيضًا الاستيرادات داخل `CLAUDE.md`، فيمكنك إضافة سطر واحد مثل `@AGENTS.md` لسحب التعليمات المشتركة دون تكرارها. + +يمكنك ببساطة استخدام: + +```bash +mv AGENTS.md CLAUDE.md +``` + +### Gemini CLI وGoogle Antigravity + +يقوم Gemini CLI وAntigravity بتحميل ملف سياق المشروع (الافتراضي: `GEMINI.md`) من جذر المستودع والمجلدات الأصلية. يمكنك تهيئته لقراءة `AGENTS.md` بدلاً من ذلك (أو بالإضافة إليه) بتعيين `context.fileName` في إعدادات Gemini CLI. على سبيل المثال، عيّنه إلى `AGENTS.md` فقط، أو أدرج كلاً من `AGENTS.md` و`GEMINI.md` إذا أردت الاحتفاظ بتنسيق كل أداة. + +يمكنك ببساطة استخدام: + +```bash +mv AGENTS.md GEMINI.md +``` + +### Cursor + +يدعم Cursor ملف `AGENTS.md` كملف تعليمات مشروع. ضعه في جذر المشروع لتوفير توجيهات لمساعد البرمجة في Cursor. + +### Windsurf + +يوفر Claude Code تكاملاً رسميًا مع Windsurf. إذا كنت تستخدم Claude Code داخل Windsurf، اتبع توجيهات Claude Code أعلاه واستورد `AGENTS.md` من `CLAUDE.md`. + +إذا كنت تستخدم مساعد Windsurf الأصلي، هيّئ ميزة قواعد أو تعليمات المشروع (إذا كانت متاحة) لقراءة `AGENTS.md` أو الصق المحتويات مباشرة. diff --git a/docs/ar/guides/concepts/evaluating-use-cases.mdx b/docs/ar/guides/concepts/evaluating-use-cases.mdx new file mode 100644 index 000000000..a0a3d5f42 --- /dev/null +++ b/docs/ar/guides/concepts/evaluating-use-cases.mdx @@ -0,0 +1,485 @@ +--- +title: تقييم حالات الاستخدام لـ CrewAI +description: تعلم كيفية تقييم احتياجات تطبيقات الذكاء الاصطناعي واختيار النهج الصحيح بين Crews وFlows بناءً على متطلبات التعقيد والدقة. +icon: scale-balanced +mode: "wide" +--- + +## فهم إطار القرار + +عند بناء تطبيقات ذكاء اصطناعي مع CrewAI، أحد أهم القرارات التي ستتخذها هو اختيار النهج الصحيح لحالة الاستخدام المحددة. هل يجب استخدام Crew؟ أم Flow؟ أم مزيج من كليهما؟ سيساعدك هذا الدليل على تقييم متطلباتك واتخاذ قرارات معمارية مدروسة. + +في جوهر هذا القرار فهم العلاقة بين **التعقيد** و**الدقة** في تطبيقك: + + + مصفوفة التعقيد مقابل الدقة + + +تساعد هذه المصفوفة في تصور كيف تتوافق النهج المختلفة مع متطلبات متفاوتة للتعقيد والدقة. لنستكشف ما يعنيه كل ربع وكيف يوجه خياراتك المعمارية. + +## شرح مصفوفة التعقيد-الدقة + +### ما هو التعقيد؟ + +في سياق تطبيقات CrewAI، يشير **التعقيد** إلى: + +- عدد الخطوات أو العمليات المميزة المطلوبة +- تنوع المهام التي يجب تنفيذها +- التبعيات المتبادلة بين المكونات المختلفة +- الحاجة للمنطق الشرطي والتفرع +- تطور سير العمل الكلي + +### ما هي الدقة؟ + +**الدقة** في هذا السياق تشير إلى: + +- الدقة المطلوبة في المخرجات النهائية +- الحاجة لنتائج منظمة وقابلة للتنبؤ +- أهمية إمكانية التكرار +- مستوى التحكم المطلوب في كل خطوة +- تحمّل التباين في المخرجات + +### الأرباع الأربعة + +#### 1. تعقيد منخفض، دقة منخفضة + +**الخصائص:** +- مهام بسيطة ومباشرة +- تحمّل بعض التباين في المخرجات +- عدد محدود من الخطوات +- تطبيقات إبداعية أو استكشافية + +**النهج الموصى به:** Crews بسيطة مع عدد قليل من الـ Agents + +**أمثلة على حالات الاستخدام:** +- إنشاء محتوى أساسي +- العصف الذهني +- مهام التلخيص البسيطة +- مساعدة الكتابة الإبداعية + +#### 2. تعقيد منخفض، دقة عالية + +**الخصائص:** +- سير عمل بسيطة تتطلب مخرجات دقيقة ومنظمة +- حاجة لنتائج قابلة للتكرار +- خطوات محدودة مع متطلبات دقة عالية +- غالبًا تتضمن معالجة أو تحويل بيانات + +**النهج الموصى به:** Flows مع استدعاءات LLM مباشرة أو Crews بسيطة مع مخرجات منظمة + +**أمثلة على حالات الاستخدام:** +- استخراج البيانات وتحويلها +- ملء النماذج والتحقق منها +- إنشاء محتوى منظم (JSON، XML) +- مهام التصنيف البسيطة + +#### 3. تعقيد عالٍ، دقة منخفضة + +**الخصائص:** +- عمليات متعددة المراحل بخطوات كثيرة +- مخرجات إبداعية أو استكشافية +- تفاعلات معقدة بين المكونات +- تحمّل التباين في النتائج النهائية + +**النهج الموصى به:** Crews معقدة مع عدة Agents متخصصة + +**أمثلة على حالات الاستخدام:** +- البحث والتحليل +- خطوط إنتاج المحتوى +- تحليل البيانات الاستكشافي +- حل المشكلات الإبداعي + +#### 4. تعقيد عالٍ، دقة عالية + +**الخصائص:** +- سير عمل معقدة تتطلب مخرجات منظمة +- خطوات مترابطة متعددة مع متطلبات دقة صارمة +- حاجة لمعالجة متطورة ونتائج دقيقة معًا +- غالبًا تطبيقات حرجة المهمة + +**النهج الموصى به:** Flows تنسّق عدة Crews مع خطوات تحقق + +**أمثلة على حالات الاستخدام:** +- أنظمة دعم القرار المؤسسية +- خطوط معالجة بيانات معقدة +- معالجة مستندات متعددة المراحل +- تطبيقات الصناعات المنظمة + +## الاختيار بين Crews وFlows + +### متى تختار Crews + +الـ Crews مثالية عندما: + +1. **تحتاج ذكاء تعاوني** - عدة Agents بتخصصات مختلفة تحتاج للعمل معًا +2. **المشكلة تتطلب تفكيرًا ناشئًا** - الحل يستفيد من منظورات ونُهج مختلفة +3. **المهمة إبداعية أو تحليلية بالأساس** - العمل يتضمن بحثًا أو إنشاء محتوى أو تحليل +4. **تقدّر القدرة على التكيف على الهيكل الصارم** - سير العمل يمكن أن يستفيد من استقلالية الـ Agent +5. **تنسيق المخرجات يمكن أن يكون مرنًا نوعًا ما** - بعض التباين في هيكل المخرجات مقبول + +```python +# Example: Research Crew for market analysis +from crewai import Agent, Crew, Process, Task + +# Create specialized agents +researcher = Agent( + role="Market Research Specialist", + goal="Find comprehensive market data on emerging technologies", + backstory="You are an expert at discovering market trends and gathering data." +) + +analyst = Agent( + role="Market Analyst", + goal="Analyze market data and identify key opportunities", + backstory="You excel at interpreting market data and spotting valuable insights." +) + +# Define their tasks +research_task = Task( + description="Research the current market landscape for AI-powered healthcare solutions", + expected_output="Comprehensive market data including key players, market size, and growth trends", + agent=researcher +) + +analysis_task = Task( + description="Analyze the market data and identify the top 3 investment opportunities", + expected_output="Analysis report with 3 recommended investment opportunities and rationale", + agent=analyst, + context=[research_task] +) + +# Create the crew +market_analysis_crew = Crew( + agents=[researcher, analyst], + tasks=[research_task, analysis_task], + process=Process.sequential, + verbose=True +) + +# Run the crew +result = market_analysis_crew.kickoff() +``` + +### متى تختار Flows + +الـ Flows مثالية عندما: + +1. **تحتاج تحكمًا دقيقًا في التنفيذ** - سير العمل يتطلب تسلسلًا دقيقًا وإدارة حالة +2. **التطبيق له متطلبات حالة معقدة** - تحتاج لصيانة وتحويل الحالة عبر خطوات متعددة +3. **تحتاج مخرجات منظمة وقابلة للتنبؤ** - التطبيق يتطلب نتائج متسقة ومنسّقة +4. **سير العمل يتضمن منطقًا شرطيًا** - مسارات مختلفة يجب اتخاذها بناءً على نتائج وسيطة +5. **تحتاج الجمع بين AI وكود إجرائي** - الحل يتطلب قدرات AI وبرمجة تقليدية معًا + +```python +# Example: Customer Support Flow with structured processing +from crewai.flow.flow import Flow, listen, router, start +from pydantic import BaseModel +from typing import List, Dict + +# Define structured state +class SupportTicketState(BaseModel): + ticket_id: str = "" + customer_name: str = "" + issue_description: str = "" + category: str = "" + priority: str = "medium" + resolution: str = "" + satisfaction_score: int = 0 + +class CustomerSupportFlow(Flow[SupportTicketState]): + @start() + def receive_ticket(self): + self.state.ticket_id = "TKT-12345" + self.state.customer_name = "Alex Johnson" + self.state.issue_description = "Unable to access premium features after payment" + return "Ticket received" + + @listen(receive_ticket) + def categorize_ticket(self, _): + from crewai import LLM + llm = LLM(model="openai/gpt-4o-mini") + + prompt = f""" + Categorize the following customer support issue into one of these categories: + - Billing + - Account Access + - Technical Issue + - Feature Request + - Other + + Issue: {self.state.issue_description} + + Return only the category name. + """ + + self.state.category = llm.call(prompt).strip() + return self.state.category + + @router(categorize_ticket) + def route_by_category(self, category): + return category.lower().replace(" ", "_") + + @listen("billing") + def handle_billing_issue(self): + self.state.priority = "high" + return "Billing issue handled" + + @listen("account_access") + def handle_access_issue(self): + self.state.priority = "high" + return "Access issue handled" + + @listen("billing", "account_access", "technical_issue", "feature_request", "other") + def resolve_ticket(self, resolution_info): + self.state.resolution = f"Issue resolved: {resolution_info}" + return self.state.resolution + +# Run the flow +support_flow = CustomerSupportFlow() +result = support_flow.kickoff() +``` + +### متى تجمع بين Crews وFlows + +أكثر التطبيقات تطورًا غالبًا تستفيد من الجمع بين Crews وFlows: + +1. **عمليات معقدة متعددة المراحل** - استخدم Flows لتنسيق العملية الكلية وCrews للمهام الفرعية المعقدة +2. **تطبيقات تتطلب إبداعًا وهيكلاً معًا** - استخدم Crews للمهام الإبداعية وFlows للمعالجة المنظمة +3. **تطبيقات AI مؤسسية** - استخدم Flows لإدارة الحالة وتدفق العمليات مع الاستفادة من Crews للعمل المتخصص + +```python +# Example: Content Production Pipeline combining Crews and Flows +from crewai.flow.flow import Flow, listen, start +from crewai import Agent, Crew, Process, Task +from pydantic import BaseModel +from typing import List, Dict + +class ContentState(BaseModel): + topic: str = "" + target_audience: str = "" + content_type: str = "" + outline: Dict = {} + draft_content: str = "" + final_content: str = "" + seo_score: int = 0 + +class ContentProductionFlow(Flow[ContentState]): + @start() + def initialize_project(self): + self.state.topic = "Sustainable Investing" + self.state.target_audience = "Millennial Investors" + self.state.content_type = "Blog Post" + return "Project initialized" + + @listen(initialize_project) + def create_outline(self, _): + researcher = Agent( + role="Content Researcher", + goal=f"Research {self.state.topic} for {self.state.target_audience}", + backstory="You are an expert researcher with deep knowledge of content creation." + ) + + outliner = Agent( + role="Content Strategist", + goal=f"Create an engaging outline for a {self.state.content_type}", + backstory="You excel at structuring content for maximum engagement." + ) + + research_task = Task( + description=f"Research {self.state.topic} focusing on what would interest {self.state.target_audience}", + expected_output="Comprehensive research notes with key points and statistics", + agent=researcher + ) + + outline_task = Task( + description=f"Create an outline for a {self.state.content_type} about {self.state.topic}", + expected_output="Detailed content outline with sections and key points", + agent=outliner, + context=[research_task] + ) + + outline_crew = Crew( + agents=[researcher, outliner], + tasks=[research_task, outline_task], + process=Process.sequential, + verbose=True + ) + + result = outline_crew.kickoff() + + import json + try: + self.state.outline = json.loads(result.raw) + except: + self.state.outline = {"sections": result.raw} + + return "Outline created" + + @listen(create_outline) + def write_content(self, _): + writer = Agent( + role="Content Writer", + goal=f"Write engaging content for {self.state.target_audience}", + backstory="You are a skilled writer who creates compelling content." + ) + + editor = Agent( + role="Content Editor", + goal="Ensure content is polished, accurate, and engaging", + backstory="You have a keen eye for detail and a talent for improving content." + ) + + writing_task = Task( + description=f"Write a {self.state.content_type} about {self.state.topic} following this outline: {self.state.outline}", + expected_output="Complete draft content in markdown format", + agent=writer + ) + + editing_task = Task( + description="Edit and improve the draft content for clarity, engagement, and accuracy", + expected_output="Polished final content in markdown format", + agent=editor, + context=[writing_task] + ) + + writing_crew = Crew( + agents=[writer, editor], + tasks=[writing_task, editing_task], + process=Process.sequential, + verbose=True + ) + + result = writing_crew.kickoff() + self.state.final_content = result.raw + + return "Content created" + + @listen(write_content) + def optimize_for_seo(self, _): + from crewai import LLM + llm = LLM(model="openai/gpt-4o-mini") + + prompt = f""" + Analyze this content for SEO effectiveness for the keyword "{self.state.topic}". + Rate it on a scale of 1-100 and provide 3 specific recommendations for improvement. + + Content: {self.state.final_content[:1000]}... (truncated for brevity) + + Format your response as JSON with the following structure: + {{ + "score": 85, + "recommendations": [ + "Recommendation 1", + "Recommendation 2", + "Recommendation 3" + ] + }} + """ + + seo_analysis = llm.call(prompt) + + import json + try: + analysis = json.loads(seo_analysis) + self.state.seo_score = analysis.get("score", 0) + return analysis + except: + self.state.seo_score = 50 + return {"score": 50, "recommendations": ["Unable to parse SEO analysis"]} + +# Run the flow +content_flow = ContentProductionFlow() +result = content_flow.kickoff() +``` + +## إطار التقييم العملي + +لتحديد النهج الصحيح لحالة استخدامك المحددة، اتبع إطار التقييم التدريجي هذا: + +### الخطوة 1: تقييم التعقيد + +قيّم تعقيد تطبيقك على مقياس من 1-10 من خلال النظر في: + +1. **عدد الخطوات**: كم عدد العمليات المميزة المطلوبة؟ + - 1-3 خطوات: تعقيد منخفض (1-3) + - 4-7 خطوات: تعقيد متوسط (4-7) + - 8+ خطوات: تعقيد عالٍ (8-10) + +2. **التبعيات المتبادلة**: ما مدى ترابط الأجزاء المختلفة؟ + - تبعيات قليلة: تعقيد منخفض (1-3) + - بعض التبعيات: تعقيد متوسط (4-7) + - تبعيات معقدة كثيرة: تعقيد عالٍ (8-10) + +3. **المنطق الشرطي**: ما مقدار التفرع وصنع القرار المطلوب؟ + - عملية خطية: تعقيد منخفض (1-3) + - بعض التفرع: تعقيد متوسط (4-7) + - أشجار قرار معقدة: تعقيد عالٍ (8-10) + +4. **المعرفة التخصصية**: ما مدى تخصص المعرفة المطلوبة؟ + - معرفة عامة: تعقيد منخفض (1-3) + - بعض المعرفة المتخصصة: تعقيد متوسط (4-7) + - خبرة عميقة في مجالات متعددة: تعقيد عالٍ (8-10) + +احسب متوسط درجتك لتحديد التعقيد الكلي. + +### الخطوة 2: تقييم متطلبات الدقة + +قيّم متطلبات الدقة على مقياس من 1-10 من خلال النظر في: + +1. **هيكل المخرجات**: ما مدى التنظيم المطلوب في المخرجات؟ + - نص حر: دقة منخفضة (1-3) + - شبه منظم: دقة متوسطة (4-7) + - منسّق بشكل صارم (JSON، XML): دقة عالية (8-10) + +2. **احتياجات الدقة**: ما أهمية الدقة الواقعية؟ + - محتوى إبداعي: دقة منخفضة (1-3) + - محتوى معلوماتي: دقة متوسطة (4-7) + - معلومات حرجة: دقة عالية (8-10) + +3. **إمكانية التكرار**: ما مدى اتساق النتائج عبر التشغيلات؟ + - التباين مقبول: دقة منخفضة (1-3) + - بعض الاتساق مطلوب: دقة متوسطة (4-7) + - تكرار دقيق مطلوب: دقة عالية (8-10) + +4. **تحمّل الأخطاء**: ما تأثير الأخطاء؟ + - تأثير منخفض: دقة منخفضة (1-3) + - تأثير معتدل: دقة متوسطة (4-7) + - تأثير عالٍ: دقة عالية (8-10) + +احسب متوسط درجتك لتحديد متطلبات الدقة الكلية. + +### الخطوة 3: التعيين على المصفوفة + +ارسم درجات التعقيد والدقة على المصفوفة: + +- **تعقيد منخفض (1-4)، دقة منخفضة (1-4)**: Crews بسيطة +- **تعقيد منخفض (1-4)، دقة عالية (5-10)**: Flows مع استدعاءات LLM مباشرة +- **تعقيد عالٍ (5-10)، دقة منخفضة (1-4)**: Crews معقدة +- **تعقيد عالٍ (5-10)، دقة عالية (5-10)**: Flows تنسّق Crews + +### الخطوة 4: مراعاة عوامل إضافية + +بالإضافة إلى التعقيد والدقة، ضع في اعتبارك: + +1. **وقت التطوير**: غالبًا ما تكون Crews أسرع في النماذج الأولية +2. **احتياجات الصيانة**: توفر Flows قابلية صيانة أفضل على المدى الطويل +3. **خبرة الفريق**: ضع في اعتبارك ألفة فريقك مع النُهج المختلفة +4. **متطلبات التوسع**: عادةً ما تتوسع Flows بشكل أفضل للتطبيقات المعقدة +5. **احتياجات التكامل**: ضع في اعتبارك كيف سيتكامل الحل مع الأنظمة الحالية + +## الخلاصة + +الاختيار بين Crews وFlows — أو الجمع بينهما — قرار معماري حاسم يؤثر على فعالية وقابلية صيانة وتوسع تطبيق CrewAI. من خلال تقييم حالة الاستخدام على أبعاد التعقيد والدقة، يمكنك اتخاذ قرارات مدروسة تتماشى مع متطلباتك المحددة. + +تذكر أن أفضل نهج غالبًا يتطور مع نضج تطبيقك. ابدأ بأبسط حل يلبي احتياجاتك، وكن مستعدًا لصقل بنيتك مع اكتساب الخبرة ووضوح المتطلبات. + + +لديك الآن إطار لتقييم حالات استخدام CrewAI واختيار النهج الصحيح بناءً على متطلبات التعقيد والدقة. سيساعدك هذا في بناء تطبيقات AI أكثر فعالية وقابلية للصيانة والتوسع. + + +## الخطوات التالية + +- تعلم المزيد عن [صياغة Agents فعّالة](/ar/guides/agents/crafting-effective-agents) +- استكشف [بناء أول Crew](/ar/guides/crews/first-crew) +- تعمّق في [إتقان إدارة حالة Flow](/ar/guides/flows/mastering-flow-state) +- اطلع على [المفاهيم الأساسية](/ar/concepts/agents) لفهم أعمق diff --git a/docs/ar/guides/crews/first-crew.mdx b/docs/ar/guides/crews/first-crew.mdx new file mode 100644 index 000000000..f8ae564b1 --- /dev/null +++ b/docs/ar/guides/crews/first-crew.mdx @@ -0,0 +1,321 @@ +--- +title: ابنِ أول Crew لك +description: دليل تفصيلي لإنشاء فريق AI تعاوني يعمل معًا لحل المشكلات المعقدة. +icon: users-gear +mode: "wide" +--- + +## إطلاق قوة الذكاء الاصطناعي التعاوني + +تخيل أن لديك فريقًا من Agents الذكاء الاصطناعي المتخصصة تعمل معًا بسلاسة لحل مشكلات معقدة، كل منها يساهم بمهاراته الفريدة لتحقيق هدف مشترك. هذه هي قوة CrewAI - إطار عمل يمكّنك من إنشاء أنظمة ذكاء اصطناعي تعاونية يمكنها إنجاز مهام تفوق بكثير ما يمكن لـ AI واحد تحقيقه بمفرده. + +في هذا الدليل، سنمشي عبر إنشاء Crew بحث يساعدنا في البحث والتحليل حول موضوع ما، ثم إنشاء تقرير شامل. يوضح هذا المثال العملي كيف يمكن لـ Agents الذكاء الاصطناعي التعاون لإنجاز مهام معقدة، لكنه مجرد البداية لما هو ممكن مع CrewAI. + +### ما ستبنيه وتتعلمه + +بنهاية هذا الدليل، ستكون قد: + +1. **أنشأت فريق بحث AI متخصص** بأدوار ومسؤوليات مميزة +2. **نسّقت التعاون** بين عدة Agents ذكاء اصطناعي +3. **أتممت سير عمل معقد** يتضمن جمع المعلومات والتحليل وإنشاء التقارير +4. **بنيت مهارات أساسية** يمكنك تطبيقها على مشاريع أكثر طموحًا + +### المتطلبات المسبقة + +قبل البدء، تأكد من: + +1. تثبيت CrewAI باتباع [دليل التثبيت](/ar/installation) +2. إعداد مفتاح API لنموذج LLM في بيئتك، باتباع [دليل إعداد LLM](/ar/concepts/llms#setting-up-your-llm) +3. فهم أساسي لـ Python + +## الخطوة 1: إنشاء مشروع CrewAI جديد + +أولاً، لننشئ مشروع CrewAI جديد باستخدام CLI. سينشئ هذا الأمر هيكل مشروع كامل بجميع الملفات الضرورية. + +```bash +crewai create crew research_crew +cd research_crew +``` + +سينتج هيكل مشروع بالبنية الأساسية المطلوبة لـ Crew. ينشئ CLI تلقائيًا: + +- مجلد مشروع بالملفات اللازمة +- ملفات تهيئة للـ Agents والمهام +- تطبيق Crew أساسي +- سكريبت رئيسي لتشغيل الـ Crew + + + نظرة عامة على إطار عمل CrewAI + + +## الخطوة 2: استكشاف هيكل المشروع + +لنخصص لحظة لفهم هيكل المشروع الذي أنشأه CLI. + +``` +research_crew/ +├── .gitignore +├── pyproject.toml +├── README.md +├── .env +└── src/ + └── research_crew/ + ├── __init__.py + ├── main.py + ├── crew.py + ├── tools/ + │ ├── custom_tool.py + │ └── __init__.py + └── config/ + ├── agents.yaml + └── tasks.yaml +``` + +يتبع هذا الهيكل أفضل الممارسات لمشاريع Python ويسهّل تنظيم الكود. فصل ملفات التهيئة (YAML) عن كود التنفيذ (Python) يسهّل تعديل سلوك Crew دون تغيير الكود الأساسي. + +## الخطوة 3: تهيئة الـ Agents + +الآن يأتي الجزء الممتع - تعريف Agents الذكاء الاصطناعي! في CrewAI، الـ Agents هي كيانات متخصصة بأدوار وأهداف وخلفيات محددة تشكّل سلوكها. + +لـ Crew البحث لدينا، سننشئ Agent اثنين: +1. **باحث** يتفوق في إيجاد وتنظيم المعلومات +2. **محلل** يمكنه تفسير نتائج البحث وإنشاء تقارير ثاقبة + +لنعدّل ملف `agents.yaml`. تأكد من تعيين `llm` للمزود الذي تستخدمه. + +```yaml +# src/research_crew/config/agents.yaml +researcher: + role: > + Senior Research Specialist for {topic} + goal: > + Find comprehensive and accurate information about {topic} + with a focus on recent developments and key insights + backstory: > + You are an experienced research specialist with a talent for + finding relevant information from various sources. You excel at + organizing information in a clear and structured manner, making + complex topics accessible to others. + llm: provider/model-id # e.g. openai/gpt-4o, google/gemini-2.0-flash, anthropic/claude... + +analyst: + role: > + Data Analyst and Report Writer for {topic} + goal: > + Analyze research findings and create a comprehensive, well-structured + report that presents insights in a clear and engaging way + backstory: > + You are a skilled analyst with a background in data interpretation + and technical writing. You have a talent for identifying patterns + and extracting meaningful insights from research data, then + communicating those insights effectively through well-crafted reports. + llm: provider/model-id # e.g. openai/gpt-4o, google/gemini-2.0-flash, anthropic/claude... +``` + +لاحظ كيف أن لكل Agent دور وهدف وخلفية مميزة. هذه العناصر ليست وصفية فحسب - بل تشكّل بنشاط كيف يتعامل الـ Agent مع مهامه. + +## الخطوة 4: تعريف المهام + +مع تعريف الـ Agents، نحتاج الآن لمنحهم مهام محددة. لنعدّل ملف `tasks.yaml`: + +```yaml +# src/research_crew/config/tasks.yaml +research_task: + description: > + Conduct thorough research on {topic}. Focus on: + 1. Key concepts and definitions + 2. Historical development and recent trends + 3. Major challenges and opportunities + 4. Notable applications or case studies + 5. Future outlook and potential developments + + Make sure to organize your findings in a structured format with clear sections. + expected_output: > + A comprehensive research document with well-organized sections covering + all the requested aspects of {topic}. Include specific facts, figures, + and examples where relevant. + agent: researcher + +analysis_task: + description: > + Analyze the research findings and create a comprehensive report on {topic}. + Your report should: + 1. Begin with an executive summary + 2. Include all key information from the research + 3. Provide insightful analysis of trends and patterns + 4. Offer recommendations or future considerations + 5. Be formatted in a professional, easy-to-read style with clear headings + expected_output: > + A polished, professional report on {topic} that presents the research + findings with added analysis and insights. The report should be well-structured + with an executive summary, main sections, and conclusion. + agent: analyst + context: + - research_task + output_file: output/report.md +``` + +لاحظ حقل `context` في مهمة التحليل - هذه ميزة قوية تتيح للمحلل الوصول إلى مخرجات مهمة البحث. + +## الخطوة 5: تهيئة الـ Crew + +الآن حان الوقت لجمع كل شيء معًا. لنعدّل ملف `crew.py`: + +```python +# src/research_crew/crew.py +from crewai import Agent, Crew, Process, Task +from crewai.project import CrewBase, agent, crew, task +from crewai_tools import SerperDevTool +from crewai.agents.agent_builder.base_agent import BaseAgent +from typing import List + +@CrewBase +class ResearchCrew(): + """Research crew for comprehensive topic analysis and reporting""" + + agents: List[BaseAgent] + tasks: List[Task] + + @agent + def researcher(self) -> Agent: + return Agent( + config=self.agents_config['researcher'], # type: ignore[index] + verbose=True, + tools=[SerperDevTool()] + ) + + @agent + def analyst(self) -> Agent: + return Agent( + config=self.agents_config['analyst'], # type: ignore[index] + verbose=True + ) + + @task + def research_task(self) -> Task: + return Task( + config=self.tasks_config['research_task'] # type: ignore[index] + ) + + @task + def analysis_task(self) -> Task: + return Task( + config=self.tasks_config['analysis_task'], # type: ignore[index] + output_file='output/report.md' + ) + + @crew + def crew(self) -> Crew: + """Creates the research crew""" + return Crew( + agents=self.agents, + tasks=self.tasks, + process=Process.sequential, + verbose=True, + ) +``` + +## الخطوة 6: إعداد السكريبت الرئيسي + +```python +#!/usr/bin/env python +# src/research_crew/main.py +import os +from research_crew.crew import ResearchCrew + +# Create output directory if it doesn't exist +os.makedirs('output', exist_ok=True) + +def run(): + """ + Run the research crew. + """ + inputs = { + 'topic': 'Artificial Intelligence in Healthcare' + } + + # Create and run the crew + result = ResearchCrew().crew().kickoff(inputs=inputs) + + # Print the result + print("\n\n=== FINAL REPORT ===\n\n") + print(result.raw) + + print("\n\nReport has been saved to output/report.md") + +if __name__ == "__main__": + run() +``` + +## الخطوة 7: إعداد متغيرات البيئة + +أنشئ ملف `.env` في جذر مشروعك بمفاتيح API: + +```sh +SERPER_API_KEY=your_serper_api_key +# Add your provider's API key here too. +``` + +راجع [دليل إعداد LLM](/ar/concepts/llms#setting-up-your-llm) لتفاصيل تهيئة المزود المفضل لديك. يمكنك الحصول على مفتاح Serper API من [Serper.dev](https://serper.dev/). + +## الخطوة 8: تثبيت التبعيات + +```bash +crewai install +``` + +## الخطوة 9: تشغيل الـ Crew + +الآن اللحظة المثيرة - حان وقت تشغيل Crew ومشاهدة التعاون بين الـ AI! + +```bash +crewai run +``` + +عند تشغيل هذا الأمر، سترى Crew يعمل. سيجمع الباحث معلومات حول الموضوع المحدد، ثم سينشئ المحلل تقريرًا شاملاً بناءً على ذلك البحث. + +## الخطوة 10: مراجعة المخرجات + +بمجرد إتمام Crew عمله، ستجد التقرير النهائي في ملف `output/report.md`. سيتضمن التقرير: + +1. ملخص تنفيذي +2. معلومات مفصلة عن الموضوع +3. تحليل ورؤى +4. توصيات أو اعتبارات مستقبلية + +## استكشاف أوامر CLI الأخرى + +يوفر CrewAI عدة أوامر CLI مفيدة للعمل مع Crews: + +```bash +# View all available commands +crewai --help + +# Run the crew +crewai run + +# Test the crew +crewai test + +# Reset crew memories +crewai reset-memories + +# Replay from a specific task +crewai replay -t +``` + +## ما بعد أول Crew: فن الممكن + +ما بنيته في هذا الدليل مجرد البداية. يمكنك توسيع Crew البحث الأساسي بإضافة Agents متخصصة أخرى وأدوات وقدرات إضافية وسير عمل أكثر تعقيدًا. يمكن تطبيق نفس الأنماط لإنشاء Crews لإنشاء المحتوى وخدمة العملاء وتطوير المنتجات وتحليل البيانات. + +## الخطوات التالية + +1. جرّب تهيئات وشخصيات Agent مختلفة +2. جرب هياكل مهام وسير عمل أكثر تعقيدًا +3. طبّق أدوات مخصصة لمنح الـ Agents قدرات جديدة +4. طبّق Crew على مواضيع أو مجالات مشكلات مختلفة +5. استكشف [CrewAI Flows](/ar/guides/flows/first-flow) لسير عمل أكثر تقدمًا مع البرمجة الإجرائية + + +تهانينا! لقد بنيت بنجاح أول CrewAI Crew يمكنه البحث والتحليل في أي موضوع تقدمه. هذه التجربة الأساسية أهّلتك بالمهارات لإنشاء أنظمة AI متطورة بشكل متزايد يمكنها معالجة مشكلات معقدة متعددة المراحل من خلال الذكاء التعاوني. + diff --git a/docs/ar/guides/flows/first-flow.mdx b/docs/ar/guides/flows/first-flow.mdx new file mode 100644 index 000000000..d4ae8f898 --- /dev/null +++ b/docs/ar/guides/flows/first-flow.mdx @@ -0,0 +1,278 @@ +--- +title: ابنِ أول Flow لك +description: تعلم كيفية إنشاء سير عمل منظمة قائمة على الأحداث مع تحكم دقيق في التنفيذ. +icon: diagram-project +mode: "wide" +--- + +## التحكم في سير عمل AI مع Flows + +تمثل CrewAI Flows المستوى التالي في تنسيق AI - الجمع بين القوة التعاونية لفرق Agents AI مع دقة ومرونة البرمجة الإجرائية. بينما تتفوق Crews في تعاون الـ Agents، تمنحك Flows تحكمًا دقيقًا في كيفية ووقت تفاعل المكونات المختلفة لنظام AI. + +في هذا الدليل، سنمشي عبر إنشاء CrewAI Flow قوي ينشئ دليلًا تعليميًا شاملاً حول أي موضوع. + +### ما يجعل Flows قوية + +تمكّنك Flows من: + +1. **الجمع بين أنماط تفاعل AI مختلفة** - استخدام Crews للمهام التعاونية المعقدة واستدعاءات LLM المباشرة للعمليات الأبسط والكود العادي للمنطق الإجرائي +2. **بناء أنظمة قائمة على الأحداث** - تحديد كيفية استجابة المكونات لأحداث وتغييرات بيانات محددة +3. **الحفاظ على الحالة عبر المكونات** - مشاركة وتحويل البيانات بين أجزاء مختلفة من تطبيقك +4. **التكامل مع الأنظمة الخارجية** - ربط سير عمل AI بسلاسة مع قواعد البيانات وواجهات API وواجهات المستخدم +5. **إنشاء مسارات تنفيذ معقدة** - تصميم فروع شرطية ومعالجة متوازية وسير عمل ديناميكية + +### المتطلبات المسبقة + +قبل البدء، تأكد من: + +1. تثبيت CrewAI باتباع [دليل التثبيت](/ar/installation) +2. إعداد مفتاح API لنموذج LLM في بيئتك، باتباع [دليل إعداد LLM](/ar/concepts/llms#setting-up-your-llm) +3. فهم أساسي لـ Python + +## الخطوة 1: إنشاء مشروع CrewAI Flow جديد + +```bash +crewai create flow guide_creator_flow +cd guide_creator_flow +``` + + + نظرة عامة على إطار عمل CrewAI + + +## الخطوة 2: فهم هيكل المشروع + +``` +guide_creator_flow/ +├── .gitignore +├── pyproject.toml +├── README.md +├── .env +├── main.py +├── crews/ +│ └── poem_crew/ +│ ├── config/ +│ │ ├── agents.yaml +│ │ └── tasks.yaml +│ └── poem_crew.py +└── tools/ + └── custom_tool.py +``` + +يوفر هذا الهيكل فصلاً واضحًا بين مكونات Flow المختلفة. سنعدّل هذا الهيكل لإنشاء Flow منشئ الدليل. + +## الخطوة 3: إضافة Crew كتابة المحتوى + +```bash +crewai flow add-crew content-crew +``` + +## الخطوة 4: تهيئة Crew كتابة المحتوى + +1. حدّث ملف تهيئة الـ Agents. تذكر تعيين `llm` للمزود الذي تستخدمه. + +```yaml +# src/guide_creator_flow/crews/content_crew/config/agents.yaml +content_writer: + role: > + Educational Content Writer + goal: > + Create engaging, informative content that thoroughly explains the assigned topic + and provides valuable insights to the reader + backstory: > + You are a talented educational writer with expertise in creating clear, engaging + content. You have a gift for explaining complex concepts in accessible language + and organizing information in a way that helps readers build their understanding. + llm: provider/model-id + +content_reviewer: + role: > + Educational Content Reviewer and Editor + goal: > + Ensure content is accurate, comprehensive, well-structured, and maintains + consistency with previously written sections + backstory: > + You are a meticulous editor with years of experience reviewing educational + content. You have an eye for detail, clarity, and coherence. + llm: provider/model-id +``` + +2. حدّث ملف تهيئة المهام: + +```yaml +# src/guide_creator_flow/crews/content_crew/config/tasks.yaml +write_section_task: + description: > + Write a comprehensive section on the topic: "{section_title}" + + Section description: {section_description} + Target audience: {audience_level} level learners + + Your content should: + 1. Begin with a brief introduction to the section topic + 2. Explain all key concepts clearly with examples + 3. Include practical applications or exercises where appropriate + 4. End with a summary of key points + 5. Be approximately 500-800 words in length + + Format your content in Markdown with appropriate headings, lists, and emphasis. + + Previously written sections: + {previous_sections} + expected_output: > + A well-structured, comprehensive section in Markdown format that thoroughly + explains the topic and is appropriate for the target audience. + agent: content_writer + +review_section_task: + description: > + Review and improve the following section on "{section_title}": + + {draft_content} + + Target audience: {audience_level} level learners + + Previously written sections: + {previous_sections} + + Your review should: + 1. Fix any grammatical or spelling errors + 2. Improve clarity and readability + 3. Ensure content is comprehensive and accurate + 4. Verify consistency with previously written sections + 5. Enhance the structure and flow + 6. Add any missing key information + expected_output: > + An improved, polished version of the section that maintains the original + structure but enhances clarity, accuracy, and consistency. + agent: content_reviewer + context: + - write_section_task +``` + +3. حدّث ملف تنفيذ Crew: + +```python +# src/guide_creator_flow/crews/content_crew/content_crew.py +from crewai import Agent, Crew, Process, Task +from crewai.project import CrewBase, agent, crew, task +from crewai.agents.agent_builder.base_agent import BaseAgent +from typing import List + +@CrewBase +class ContentCrew(): + """Content writing crew""" + + agents: List[BaseAgent] + tasks: List[Task] + + @agent + def content_writer(self) -> Agent: + return Agent( + config=self.agents_config['content_writer'], # type: ignore[index] + verbose=True + ) + + @agent + def content_reviewer(self) -> Agent: + return Agent( + config=self.agents_config['content_reviewer'], # type: ignore[index] + verbose=True + ) + + @task + def write_section_task(self) -> Task: + return Task( + config=self.tasks_config['write_section_task'] # type: ignore[index] + ) + + @task + def review_section_task(self) -> Task: + return Task( + config=self.tasks_config['review_section_task'], # type: ignore[index] + context=[self.write_section_task()] + ) + + @crew + def crew(self) -> Crew: + """Creates the content writing crew""" + return Crew( + agents=self.agents, + tasks=self.tasks, + process=Process.sequential, + verbose=True, + ) +``` + +## الخطوة 5: إنشاء Flow + +الآن الجزء المثير - إنشاء Flow الذي سينسّق عملية إنشاء الدليل بالكامل. راجع الملف الإنجليزي الأصلي للكود الكامل لـ `main.py` حيث أن الكود يبقى كما هو. + +## الخطوة 6: إعداد متغيرات البيئة + +أنشئ ملف `.env` في جذر مشروعك بمفاتيح API. راجع [دليل إعداد LLM](/ar/concepts/llms#setting-up-your-llm) لتفاصيل تهيئة المزود. + +```sh .env +OPENAI_API_KEY=your_openai_api_key +# or +GEMINI_API_KEY=your_gemini_api_key +# or +ANTHROPIC_API_KEY=your_anthropic_api_key +``` + +## الخطوة 7: تثبيت التبعيات + +```bash +crewai install +``` + +## الخطوة 8: تشغيل Flow + +```bash +crewai flow kickoff +``` + +عند تشغيل هذا الأمر، ستشاهد Flow يعمل: +1. سيطلب منك موضوعًا ومستوى الجمهور +2. سينشئ مخططًا منظمًا لدليلك +3. سيعالج كل قسم مع تعاون الكاتب والمراجع +4. أخيرًا سيجمع كل شيء في دليل شامل + +## الخطوة 9: تصوير Flow + +```bash +crewai flow plot +``` + +سينشئ ملف HTML يوضح هيكل Flow بما في ذلك العلاقات بين الخطوات المختلفة. + +## الخطوة 10: مراجعة المخرجات + +بمجرد اكتمال Flow، ستجد ملفين في مجلد `output`: + +1. `guide_outline.json`: يحتوي على المخطط المنظم للدليل +2. `complete_guide.md`: الدليل الشامل بجميع الأقسام + +## الميزات الرئيسية الموضّحة + +يوضح Flow منشئ الدليل عدة ميزات قوية لـ CrewAI: + +1. **تفاعل المستخدم**: يجمع Flow مدخلات مباشرة من المستخدم +2. **استدعاءات LLM المباشرة**: يستخدم فئة LLM لتفاعلات AI فعّالة وأحادية الغرض +3. **بيانات منظمة مع Pydantic**: يستخدم نماذج Pydantic لضمان سلامة الأنواع +4. **معالجة تسلسلية مع سياق**: يكتب الأقسام بالترتيب ويوفر الأقسام السابقة كسياق +5. **Crews متعددة الـ Agents**: يستفيد من Agents متخصصة (كاتب ومراجع) لإنشاء المحتوى +6. **إدارة الحالة**: يحافظ على الحالة عبر خطوات العملية المختلفة +7. **بنية قائمة على الأحداث**: يستخدم مزخرف `@listen` للاستجابة للأحداث + +## الخطوات التالية + +1. جرّب هياكل Flow أكثر تعقيدًا وأنماطًا +2. جرّب استخدام `@router()` لإنشاء فروع شرطية +3. استكشف دوال `and_` و`or_` لتنفيذ متوازٍ أكثر تعقيدًا +4. اربط Flow بواجهات API خارجية وقواعد بيانات وواجهات مستخدم +5. ادمج عدة Crews متخصصة في Flow واحد + + +تهانينا! لقد بنيت بنجاح أول CrewAI Flow يجمع بين الكود العادي واستدعاءات LLM المباشرة ومعالجة Crew لإنشاء دليل شامل. هذه المهارات الأساسية تمكّنك من إنشاء تطبيقات AI متطورة بشكل متزايد. + diff --git a/docs/ar/guides/flows/mastering-flow-state.mdx b/docs/ar/guides/flows/mastering-flow-state.mdx new file mode 100644 index 000000000..64874e39c --- /dev/null +++ b/docs/ar/guides/flows/mastering-flow-state.mdx @@ -0,0 +1,184 @@ +--- +title: إتقان إدارة حالة Flow +description: دليل شامل لإدارة الحالة وحفظها والاستفادة منها في CrewAI Flows لبناء تطبيقات AI قوية. +icon: diagram-project +mode: "wide" +--- + +## فهم قوة الحالة في Flows + +إدارة الحالة هي العمود الفقري لأي سير عمل AI متطور. في CrewAI Flows، يتيح لك نظام الحالة الحفاظ على السياق ومشاركة البيانات بين الخطوات وبناء منطق تطبيق معقد. إتقان إدارة الحالة ضروري لإنشاء تطبيقات AI موثوقة وقابلة للصيانة وقوية. + +### لماذا تهم إدارة الحالة + +تمكّنك إدارة الحالة الفعّالة من: + +1. **الحفاظ على السياق عبر خطوات التنفيذ** - تمرير المعلومات بسلاسة بين مراحل سير العمل المختلفة +2. **بناء منطق شرطي معقد** - اتخاذ قرارات بناءً على البيانات المتراكمة +3. **إنشاء تطبيقات مستمرة** - حفظ واستعادة تقدم سير العمل +4. **معالجة الأخطاء بلطف** - تنفيذ أنماط استرداد لتطبيقات أكثر قوة +5. **توسيع تطبيقاتك** - دعم سير العمل المعقدة بتنظيم بيانات مناسب +6. **تمكين التطبيقات الحوارية** - تخزين والوصول إلى سجل المحادثات للتفاعلات الواعية بالسياق + +## أساسيات إدارة الحالة + +### نهجان لإدارة الحالة + +يوفر CrewAI طريقتين لإدارة الحالة في Flows: + +1. **الحالة غير المنظمة** - استخدام كائنات شبيهة بالقاموس للمرونة +2. **الحالة المنظمة** - استخدام نماذج Pydantic لسلامة الأنواع والتحقق + +### مثال الحالة غير المنظمة + +```python +from crewai.flow.flow import Flow, listen, start + +class UnstructuredStateFlow(Flow): + @start() + def initialize_data(self): + self.state["user_name"] = "Alex" + self.state["preferences"] = {"theme": "dark", "language": "English"} + self.state["items"] = [] + return "Initialized" + + @listen(initialize_data) + def process_data(self, previous_result): + user = self.state["user_name"] + self.state["items"].append("item1") + self.state["processed"] = True + return "Processed" + +flow = UnstructuredStateFlow() +result = flow.kickoff() +``` + +### مثال الحالة المنظمة + +```python +from crewai.flow.flow import Flow, listen, start +from pydantic import BaseModel, Field +from typing import List, Dict, Optional + +class AppState(BaseModel): + user_name: str = "" + items: List[str] = [] + processed: bool = False + completion_percentage: float = 0.0 + +class StructuredStateFlow(Flow[AppState]): + @start() + def initialize_data(self): + self.state.user_name = "Taylor" + return "Initialized" + + @listen(initialize_data) + def process_data(self, previous_result): + self.state.items.append("item1") + self.state.processed = True + self.state.completion_percentage = 50.0 + return "Processed" + +flow = StructuredStateFlow() +result = flow.kickoff() +``` + +### فوائد الحالة المنظمة + +1. **سلامة الأنواع** - اكتشاف أخطاء الأنواع في وقت التطوير +2. **توثيق ذاتي** - نموذج الحالة يوثّق بوضوح البيانات المتاحة +3. **التحقق** - التحقق التلقائي من أنواع البيانات والقيود +4. **دعم IDE** - إكمال تلقائي وتوثيق مضمّن +5. **قيم افتراضية** - تعريف بدائل سهلة للبيانات المفقودة + +## حفظ حالة Flow + +يوفر مزخرف `@persist()` حفظ حالة تلقائي عند نقاط رئيسية في التنفيذ. + +```python +from crewai.flow.flow import Flow, listen, start +from crewai.flow.persistence import persist +from pydantic import BaseModel + +class CounterState(BaseModel): + value: int = 0 + +@persist() +class PersistentCounterFlow(Flow[CounterState]): + @start() + def increment(self): + self.state.value += 1 + return self.state.value + + @listen(increment) + def double(self, value): + self.state.value = value * 2 + return self.state.value +``` + +## أنماط حالة متقدمة + +### المنطق الشرطي المبني على الحالة + +```python +from crewai.flow.flow import Flow, listen, router, start +from pydantic import BaseModel + +class PaymentState(BaseModel): + amount: float = 0.0 + is_approved: bool = False + retry_count: int = 0 + +class PaymentFlow(Flow[PaymentState]): + @start() + def process_payment(self): + self.state.amount = 100.0 + self.state.is_approved = self.state.amount < 1000 + return "Payment processed" + + @router(process_payment) + def check_approval(self, previous_result): + if self.state.is_approved: + return "approved" + elif self.state.retry_count < 3: + return "retry" + else: + return "rejected" + + @listen("approved") + def handle_approval(self): + return f"Payment of ${self.state.amount} approved!" + + @listen("retry") + def handle_retry(self): + self.state.retry_count += 1 + return "Retry initiated" + + @listen("rejected") + def handle_rejection(self): + return f"Payment of ${self.state.amount} rejected after {self.state.retry_count} retries." +``` + +## أفضل الممارسات لإدارة الحالة + +1. **اجعل الحالة مركّزة** - صمم الحالة لتحتوي فقط على ما هو ضروري +2. **استخدم الحالة المنظمة للـ Flows المعقدة** - مع نمو التعقيد تصبح الحالة المنظمة أكثر قيمة +3. **وثّق انتقالات الحالة** - للـ Flows المعقدة، وثّق كيف تتغير الحالة عبر التنفيذ +4. **عالج أخطاء الحالة بلطف** - طبّق معالجة أخطاء للوصول إلى الحالة +5. **استخدم الحالة لتتبع التقدم** - استفد من الحالة لتتبع التقدم في Flows طويلة التشغيل +6. **استخدم العمليات غير المتغيرة عند الإمكان** - خاصة مع الحالة المنظمة + +## الخلاصة + +إتقان إدارة الحالة في CrewAI Flows يمنحك القدرة على بناء تطبيقات AI متطورة وقوية تحافظ على السياق وتتخذ قرارات معقدة وتقدم نتائج متسقة. + + +لقد أتقنت الآن مفاهيم وممارسات إدارة الحالة في CrewAI Flows! بهذه المعرفة، يمكنك إنشاء سير عمل AI قوية تحافظ على السياق بفعالية وتشارك البيانات بين الخطوات وتبني منطق تطبيق متطور. + + +## الخطوات التالية + +- جرّب الحالة المنظمة وغير المنظمة في Flows +- جرّب تطبيق حفظ الحالة لسير العمل طويلة التشغيل +- استكشف [بناء أول Crew](/ar/guides/crews/first-crew) لمعرفة كيف تعمل Crews وFlows معًا +- اطلع على [توثيق مرجع Flow](/ar/concepts/flows) لمزيد من الميزات المتقدمة diff --git a/docs/ar/guides/migration/migrating-from-langgraph.mdx b/docs/ar/guides/migration/migrating-from-langgraph.mdx new file mode 100644 index 000000000..913854ae8 --- /dev/null +++ b/docs/ar/guides/migration/migrating-from-langgraph.mdx @@ -0,0 +1,103 @@ +--- +title: "الانتقال من LangGraph إلى CrewAI: دليل عملي للمهندسين" +description: إذا كنت قد بنيت بالفعل مع LangGraph، تعلم كيفية نقل مشاريعك بسرعة إلى CrewAI +icon: switch +mode: "wide" +--- + +لقد بنيت Agents مع LangGraph. لقد تعاملت مع `StateGraph`، وربطت الحواف الشرطية، وصححت أخطاء قواميس الحالة في الثانية صباحًا. إنه يعمل — لكن في مرحلة ما، بدأت تتساءل عما إذا كان هناك مسار أفضل نحو الإنتاج. + +هناك بالفعل. **CrewAI Flows** يمنحك نفس القوة — تنسيق قائم على الأحداث، توجيه شرطي، حالة مشتركة — مع نموذج كود أبسط بشكل كبير ونموذج ذهني يتماشى مع طريقة تفكيرك الفعلية في سير عمل AI متعدد الخطوات. + +تمشي هذه المقالة عبر المفاهيم الأساسية جنبًا إلى جنب، وتعرض مقارنات كود حقيقية، وتوضح لماذا CrewAI Flows هو إطار العمل الذي ستريد الوصول إليه بعد ذلك. + +--- + +## تحول النموذج الذهني + +LangGraph يطلب منك التفكير في **رسوم بيانية**: عقد وحواف وقواميس حالة. كل سير عمل هو رسم بياني موجّه تربط فيه الانتقالات صراحةً بين خطوات الحساب. + +CrewAI Flows يطلب منك التفكير في **أحداث**: طرق تبدأ الأشياء، وطرق تستمع للنتائج، وطرق توجّه التنفيذ. طوبولوجيا سير العمل تنبثق من تعليقات المزخرفات بدلاً من بناء رسم بياني صريح. + +إليك الخريطة الأساسية: + +| مفهوم LangGraph | المكافئ في CrewAI Flows | +| --- | --- | +| `StateGraph` class | `Flow` class | +| `add_node()` | طرق مزخرفة بـ `@start`، `@listen` | +| `add_edge()` / `add_conditional_edges()` | مزخرفات `@listen()` / `@router()` | +| `TypedDict` state | حالة Pydantic `BaseModel` | +| `START` / `END` constants | مزخرف `@start()` / إرجاع طبيعي للطريقة | +| `graph.compile()` | `flow.kickoff()` | +| Checkpointer / persistence | ذاكرة مدمجة (مدعومة بـ LanceDB) | + +--- + +## العرض 1: خط أنابيب تسلسلي بسيط + +تخيل أنك تبني خط أنابيب يأخذ موضوعًا، ويبحث فيه، ويكتب ملخصًا، وينسّق المخرجات. راجع الملف الإنجليزي الأصلي لأمثلة الكود الكاملة لكلا النهجين. + +الفرق الرئيسي: لا بناء رسم بياني، لا ربط حواف، لا خطوة ترجمة. ترتيب التنفيذ مُعلَن مباشرة حيث يوجد المنطق. `@start()` يحدد نقطة الدخول، و`@listen(method_name)` يربط الخطوات. + +--- + +## العرض 2: التوجيه الشرطي + +مزخرف `@router()` يحوّل طريقة إلى نقطة قرار. يعيد سلسلة تطابق مستمعًا — بلا قواميس تعيين، بلا دوال توجيه منفصلة. منطق التفرع يُقرأ كتعبير `if` في Python لأنه كذلك فعلاً. + +--- + +## العرض 3: دمج فرق Agents AI في Flows + +هنا تتجلى القوة الحقيقية لـ CrewAI. الـ Flows لا تقتصر على ربط استدعاءات LLM — بل تنسّق **Crews** كاملة من Agents مستقلة. + +الفكرة الرئيسية: **الـ Flows توفر طبقة التنسيق، والـ Crews توفر طبقة الذكاء.** كل خطوة في Flow يمكنها تشغيل فريق كامل من Agents متعاونة. + +--- + +## العرض 4: التنفيذ المتوازي والمزامنة + +المشغّل `and_()` على مزخرف `@listen` يضمن أن الطريقة تُنفَّذ فقط بعد اكتمال *جميع* الطرق السابقة. هناك أيضًا `or_()` للمتابعة بمجرد اكتمال *أي* مهمة سابقة. + +--- + +## لماذا CrewAI Flows للإنتاج + +- **حفظ حالة مدمج.** حالة Flow مدعومة بـ LanceDB. +- **إدارة حالة آمنة الأنواع.** نماذج Pydantic توفر التحقق والتسلسل ودعم IDE. +- **تنسيق Agents أصلي.** الـ Crews بنية أساسية أصلية. +- **نموذج ذهني أبسط.** المزخرفات تعلن عن النية. +- **تكامل CLI.** شغّل Flows بـ `crewai run`. + +--- + +## ورقة الغش للترحيل + +1. **عيّن حالتك.** حوّل `TypedDict` إلى Pydantic `BaseModel`. +2. **حوّل العقد إلى طرق.** كل دالة `add_node` تصبح طريقة على فئة `Flow` الفرعية. +3. **استبدل الحواف بمزخرفات.** `add_edge(START, "first_node")` يصبح `@start()`. `add_edge("a", "b")` يصبح `@listen(a)`. +4. **استبدل الحواف الشرطية بـ `@router`.** دالة التوجيه و`add_conditional_edges()` تصبح طريقة `@router()` واحدة. +5. **استبدل compile + invoke بـ kickoff.** احذف `graph.compile()`. استدعِ `flow.kickoff()` بدلاً منه. +6. **فكّر أين تناسب الـ Crews.** أي عقدة بها منطق Agent معقد متعدد الخطوات هي مرشحة لاستخراجها في Crew. + +--- + +## البدء + +```bash +pip install crewai +crewai create flow my_first_flow +cd my_first_flow +``` + +```bash +crewai run +``` + +--- + +## أفكار أخيرة + +LangGraph علّم المنظومة أن سير عمل AI تحتاج هيكلاً. كان ذلك درسًا مهمًا. لكن CrewAI Flows يأخذ ذلك الدرس ويقدمه في شكل أسرع في الكتابة وأسهل في القراءة وأقوى في الإنتاج — خاصة عندما تتضمن سير عملك عدة Agents متعاونة. + +ابدأ بـ `crewai create flow`. لن تنظر للخلف. diff --git a/docs/ar/guides/tools/publish-custom-tools.mdx b/docs/ar/guides/tools/publish-custom-tools.mdx new file mode 100644 index 000000000..f181e0e25 --- /dev/null +++ b/docs/ar/guides/tools/publish-custom-tools.mdx @@ -0,0 +1,96 @@ +--- +title: نشر أدوات مخصصة +description: كيفية بناء وتعبئة ونشر أدواتك الخاصة المتوافقة مع CrewAI على PyPI ليتمكن أي مستخدم CrewAI من تثبيتها واستخدامها. +icon: box-open +mode: "wide" +--- + +## نظرة عامة + +نظام الأدوات في CrewAI مصمم للتوسيع. إذا بنيت أداة يمكن أن تفيد الآخرين، يمكنك تعبئتها كمكتبة Python مستقلة ونشرها على PyPI وإتاحتها لأي مستخدم CrewAI — دون الحاجة لطلب سحب إلى مستودع CrewAI. + +يمشي هذا الدليل عبر العملية الكاملة: تنفيذ عقد الأدوات، وهيكلة حزمتك، والنشر على PyPI. + + +إذا كنت تحتاج فقط أداة مخصصة لمشروعك، راجع دليل [إنشاء أدوات مخصصة](/ar/learn/create-custom-tools) بدلاً من ذلك. + + +## عقد الأدوات + +كل أداة CrewAI يجب أن تستوفي إحدى الواجهتين: + +### الخيار 1: وراثة `BaseTool` + +ورث من `crewai.tools.BaseTool` وطبّق طريقة `_run`. عرّف `name` و`description` واختياريًا `args_schema` للتحقق من المدخلات. + +```python +from crewai.tools import BaseTool +from pydantic import BaseModel, Field + + +class GeolocateInput(BaseModel): + """Input schema for GeolocateTool.""" + address: str = Field(..., description="The street address to geolocate.") + + +class GeolocateTool(BaseTool): + name: str = "Geolocate" + description: str = "Converts a street address into latitude/longitude coordinates." + args_schema: type[BaseModel] = GeolocateInput + + def _run(self, address: str) -> str: + return f"40.7128, -74.0060" +``` + +### الخيار 2: استخدام مزخرف `@tool` + +للأدوات الأبسط، يحوّل مزخرف `@tool` دالة إلى أداة CrewAI. يجب أن تحتوي الدالة على سلسلة توثيق (تُستخدم كوصف الأداة) وتعليقات أنواع. + +```python +from crewai.tools import tool + + +@tool("Geolocate") +def geolocate(address: str) -> str: + """Converts a street address into latitude/longitude coordinates.""" + return "40.7128, -74.0060" +``` + +### المتطلبات الأساسية + +بغض النظر عن النهج الذي تستخدمه، يجب أن تحتوي أداتك على: + +- **`name`** — معرّف قصير ووصفي. +- **`description`** — يخبر الـ Agent متى وكيف يستخدم الأداة. +- **`_run`** (BaseTool) أو **جسم الدالة** (@tool) — منطق التنفيذ المتزامن. +- **تعليقات أنواع** على جميع المعاملات وقيم الإرجاع. +- إرجاع نتيجة **نصية** (أو شيء يمكن تحويله لنص). + +## هيكل الحزمة + +``` +crewai-geolocate/ +├── pyproject.toml +├── LICENSE +├── README.md +└── src/ + └── crewai_geolocate/ + ├── __init__.py + └── tools.py +``` + +## النشر على PyPI + +```bash +# Build the package +uv build + +# Publish to PyPI +uv publish +``` + +بعد النشر، يمكن للمستخدمين تثبيت أداتك بـ: + +```bash +uv add crewai-geolocate +``` diff --git a/docs/ar/index.mdx b/docs/ar/index.mdx new file mode 100644 index 000000000..d74de8278 --- /dev/null +++ b/docs/ar/index.mdx @@ -0,0 +1,105 @@ +--- +title: "توثيق CrewAI" +description: "ابنِ Agents ذكاء اصطناعي تعاونية وCrews وFlows — جاهزة للإنتاج من اليوم الأول." +icon: "house" +mode: "wide" +--- + +
+ CrewAI +
+

أطلق أنظمة متعددة الـ Agents بثقة

+

+ صمم Agents، ونسّق Crews، وأتمت Flows مع حواجز حماية وذاكرة ومعرفة ومراقبة مدمجة. +

+
+ + + +
+ +
+ +## ابدأ + + + + نظرة عامة على مفاهيم CrewAI وبنيته المعمارية وما يمكنك بناؤه باستخدام Agents وCrews وFlows. + + + التثبيت عبر `uv`، وإعداد مفاتيح API، وتهيئة CLI للتطوير المحلي. + + + أنشئ أول Crew لك في دقائق. تعلم بيئة التشغيل الأساسية وهيكل المشروع ودورة التطوير. + + + +## ابنِ الأساسيات + + + + أنشئ Agents بأدوات وذاكرة ومعرفة ومخرجات منظمة باستخدام Pydantic. يتضمن قوالب وأفضل الممارسات. + + + نسّق خطوات start/listen/router، وأدر الحالة، واحفظ التنفيذ، واستأنف سير العمل الطويل. + + + حدد عمليات متسلسلة أو هرمية أو مختلطة مع حواجز حماية واستدعاءات راجعة ومحفزات تدخل بشري. + + + +## رحلة المؤسسات + + + + إدارة البيئات وإعادة النشر بأمان ومراقبة التشغيل المباشر من لوحة تحكم المؤسسات. + + + ربط Gmail وSlack وSalesforce والمزيد. تمرير بيانات المحفزات إلى Crews وFlows تلقائيًا. + + + دعوة أعضاء الفريق وتهيئة التحكم في الوصول المبني على الأدوار وإدارة الوصول إلى أتمتة الإنتاج. + + + +## ما الجديد + + + + نظرة شاملة موحدة على Gmail وDrive وOutlook وTeams وOneDrive وHubSpot والمزيد — الآن مع نماذج بيانات وCrews. + + + استدعاء أتمتة CrewAI الحالية أو Amazon Bedrock Agents مباشرة من Crews باستخدام مجموعة أدوات التكامل المحدّثة. + + + + + تصفح الأمثلة وكتب الوصفات للحصول على تطبيقات مرجعية شاملة عبر Agents وFlows وأتمتة المؤسسات. + + +## ابقَ على تواصل + + + + إذا ساعدك CrewAI في الإطلاق بشكل أسرع، امنحنا نجمة وشارك مشاريعك مع المجتمع. + + + اطرح أسئلة واعرض سير العمل واطلب ميزات جديدة جنبًا إلى جنب مع المطورين الآخرين. + + diff --git a/docs/ar/installation.mdx b/docs/ar/installation.mdx new file mode 100644 index 000000000..3a902fae0 --- /dev/null +++ b/docs/ar/installation.mdx @@ -0,0 +1,217 @@ +--- +title: التثبيت +description: ابدأ مع CrewAI - التثبيت والتهيئة وبناء أول فريق AI +icon: wrench +mode: "wide" +--- + +### شاهد: بناء Agents و Flows في CrewAI باستخدام Coding Agent Skills + +قم بتثبيت مهارات وكيل البرمجة الخاصة بنا (Claude Code، Codex، ...) لتشغيل وكلاء البرمجة بسرعة مع CrewAI. + +يمكنك تثبيتها باستخدام `npx skills add crewaiinc/skills` + + + +## فيديو تعليمي + +شاهد هذا الفيديو التعليمي لعرض تفصيلي لعملية التثبيت: + + + +## دليل نصي + + + **متطلبات إصدار Python** + +يتطلب CrewAI إصدار `Python >=3.10 and <3.14`. إليك كيفية التحقق من إصدارك: + +```bash +python3 --version +``` + +إذا كنت بحاجة لتحديث Python، قم بزيارة [python.org/downloads](https://python.org/downloads) + + + + + **متطلبات OpenAI SDK** + +يتطلب CrewAI 0.175.0 إصدار `openai >= 1.13.3`. إذا كنت تدير التبعيات بنفسك، تأكد من أن بيئتك تستوفي هذا الشرط لتجنب مشاكل الاستيراد/التشغيل. + + + +يستخدم CrewAI أداة `uv` لإدارة التبعيات والحزم. وهي تبسّط إعداد المشروع وتنفيذه وتوفر تجربة سلسة. + +إذا لم تكن قد ثبّتت `uv` بعد، اتبع **الخطوة 1** لإعدادها بسرعة على نظامك، وإلا يمكنك الانتقال إلى **الخطوة 2**. + + + + - **على macOS/Linux:** + + استخدم `curl` لتحميل السكريبت وتنفيذه عبر `sh`: + + ```shell + curl -LsSf https://astral.sh/uv/install.sh | sh + ``` + إذا لم يكن `curl` متاحًا على نظامك، يمكنك استخدام `wget`: + + ```shell + wget -qO- https://astral.sh/uv/install.sh | sh + ``` + + - **على Windows:** + + استخدم `irm` لتحميل السكريبت و`iex` لتنفيذه: + + ```shell + powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" + ``` + إذا واجهت أي مشاكل، راجع [دليل تثبيت UV](https://docs.astral.sh/uv/getting-started/installation/) لمزيد من المعلومات. + + + + - شغّل الأمر التالي لتثبيت واجهة سطر أوامر `crewai`: + ```shell + uv tool install crewai + ``` + + إذا ظهر تحذير بشأن `PATH`، شغّل هذا الأمر لتحديث الصدفة: + ```shell + uv tool update-shell + ``` + + + + إذا واجهت خطأ بناء `chroma-hnswlib==0.7.6` (`fatal error C1083: Cannot open include file: 'float.h'`) على Windows، ثبّت [Visual Studio Build Tools](https://visualstudio.microsoft.com/downloads/) مع خيار *Desktop development with C++*. + + + - للتحقق من تثبيت `crewai`، شغّل: + ```shell + uv tool list + ``` + - يجب أن ترى شيئًا مثل: + ```shell + crewai v0.102.0 + - crewai + ``` + - إذا كنت بحاجة لتحديث `crewai`، شغّل: + ```shell + uv tool install crewai --upgrade + ``` + تم التثبيت بنجاح! أنت جاهز لإنشاء أول Crew! + + + + +# إنشاء مشروع CrewAI + +نوصي باستخدام قالب `YAML` لنهج منظم في تعريف الـ Agents والمهام. إليك كيفية البدء: + + + + - شغّل أمر `crewai` عبر CLI: + ```shell + crewai create crew + ``` + + - سينشئ هذا مشروعًا جديدًا بالهيكل التالي: + ``` + my_project/ + ├── .gitignore + ├── knowledge/ + ├── pyproject.toml + ├── README.md + ├── .env + └── src/ + └── my_project/ + ├── __init__.py + ├── main.py + ├── crew.py + ├── tools/ + │ ├── custom_tool.py + │ └── __init__.py + └── config/ + ├── agents.yaml + └── tasks.yaml + ``` + + + + + - سيحتوي مشروعك على هذه الملفات الأساسية: + | الملف | الغرض | + | --- | --- | + | `agents.yaml` | تعريف الـ Agents وأدوارهم | + | `tasks.yaml` | إعداد مهام الـ Agents وسير العمل | + | `.env` | تخزين مفاتيح API ومتغيرات البيئة | + | `main.py` | نقطة دخول المشروع وتدفق التنفيذ | + | `crew.py` | تنسيق وإدارة الـ Crew | + | `tools/` | مجلد الأدوات المخصصة | + | `knowledge/` | مجلد قاعدة المعرفة | + + - ابدأ بتحرير `agents.yaml` و`tasks.yaml` لتعريف سلوك الـ Crew. + - احتفظ بالمعلومات الحساسة مثل مفاتيح API في `.env`. + + + + + - قبل تشغيل الـ Crew، تأكد من تنفيذ: + ```bash + crewai install + ``` + - إذا كنت بحاجة لتثبيت حزم إضافية، استخدم: + ```shell + uv add + ``` + - لتشغيل الـ Crew، نفّذ الأمر التالي في جذر مشروعك: + ```bash + crewai run + ``` + + + +## خيارات التثبيت للمؤسسات + + +للفرق والمؤسسات، يوفر CrewAI خيارات نشر مؤسسية تزيل تعقيد الإعداد: + +### CrewAI AMP (SaaS) + +- لا يتطلب أي تثبيت - فقط سجّل مجانًا على [app.crewai.com](https://app.crewai.com) +- تحديثات وصيانة تلقائية +- بنية تحتية مُدارة وقابلة للتوسع +- بناء Crews بدون كتابة كود + +### CrewAI Factory (استضافة ذاتية) + +- نشر بالحاويات على بنيتك التحتية +- يدعم أي مزود سحابي بما في ذلك النشر المحلي +- تكامل مع أنظمة الأمان الحالية + + + تعرّف على عروض CrewAI للمؤسسات وجدول عرضًا توضيحيًا + + + +## الخطوات التالية + + + + اتبع البداية السريعة لإنشاء Flow وتشغيل طاقم بوكيل واحد وإنتاج تقرير. + + + تواصل مع مطورين آخرين واحصل على المساعدة وشارك تجاربك مع CrewAI. + + diff --git a/docs/ar/introduction.mdx b/docs/ar/introduction.mdx new file mode 100644 index 000000000..58d441c6e --- /dev/null +++ b/docs/ar/introduction.mdx @@ -0,0 +1,152 @@ +--- +title: مقدمة +description: ابنِ فرق Agents ذكاء اصطناعي تعمل معًا لمعالجة المهام المعقدة +icon: handshake +mode: "wide" +--- + +# ما هو CrewAI؟ + +**CrewAI هو إطار العمل مفتوح المصدر الرائد لتنسيق Agents الذكاء الاصطناعي المستقلة وبناء سير العمل المعقدة.** + +يمكّن المطورين من بناء أنظمة متعددة الـ Agents جاهزة للإنتاج من خلال الجمع بين الذكاء التعاوني لـ **Crews** والتحكم الدقيق لـ **Flows**. + +- **[CrewAI Flows](/ar/guides/flows/first-flow)**: العمود الفقري لتطبيق الذكاء الاصطناعي. تتيح لك Flows إنشاء سير عمل منظمة قائمة على الأحداث تدير الحالة وتتحكم في التنفيذ. وهي توفر البنية الأساسية التي تعمل ضمنها Agents الذكاء الاصطناعي. +- **[CrewAI Crews](/ar/guides/crews/first-crew)**: وحدات العمل ضمن Flow. الـ Crews هي فرق من Agents مستقلة تتعاون لحل مهام محددة يفوضها إليها Flow. + +مع أكثر من 100,000 مطور معتمد عبر دوراتنا المجتمعية، يُعد CrewAI المعيار لأتمتة الذكاء الاصطناعي الجاهزة للمؤسسات. + +### شاهد: بناء Agents و Flows في CrewAI باستخدام Coding Agent Skills + +قم بتثبيت مهارات وكيل البرمجة الخاصة بنا (Claude Code، Codex، ...) لتشغيل وكلاء البرمجة بسرعة مع CrewAI. + +يمكنك تثبيتها باستخدام `npx skills add crewaiinc/skills` + + + +## بنية CrewAI المعمارية + +صُممت بنية CrewAI لتحقيق التوازن بين الاستقلالية والتحكم. + +### 1. Flows: العمود الفقري + + + فكّر في Flow كـ "المدير" أو "تعريف العملية" لتطبيقك. يحدد الخطوات والمنطق وكيفية تدفق البيانات عبر نظامك. + + + + نظرة عامة على إطار عمل CrewAI + + +توفر Flows: +- **إدارة الحالة**: حفظ البيانات عبر الخطوات والتنفيذات. +- **تنفيذ قائم على الأحداث**: تشغيل إجراءات بناءً على أحداث أو مدخلات خارجية. +- **التحكم في التدفق**: استخدام المنطق الشرطي والحلقات والتفرع. + +### 2. Crews: الذكاء + + + الـ Crews هي "الفرق" التي تقوم بالعمل الثقيل. ضمن Flow، يمكنك تشغيل Crew لمعالجة مشكلة معقدة تتطلب إبداعًا وتعاونًا. + + + + نظرة عامة على إطار عمل CrewAI + + +توفر Crews: +- **Agents بأدوار محددة**: Agents متخصصة بأهداف وأدوات محددة. +- **تعاون مستقل**: تعمل الـ Agents معًا لحل المهام. +- **تفويض المهام**: يتم تعيين المهام وتنفيذها بناءً على قدرات الـ Agent. + +## كيف يعمل الكل معًا + +1. يبدأ **Flow** حدثًا أو يشغّل عملية. +2. يدير **Flow** الحالة ويقرر ما يجب فعله بعد ذلك. +3. يفوّض **Flow** مهمة معقدة إلى **Crew**. +4. تتعاون Agents الـ **Crew** لإكمال المهمة. +5. يعيد **Crew** النتيجة إلى **Flow**. +6. يستمر **Flow** في التنفيذ بناءً على النتيجة. + +## الميزات الرئيسية + + + + ابنِ سير عمل موثوقة وذات حالة يمكنها التعامل مع العمليات طويلة التشغيل والمنطق المعقد. + + + انشر فرقًا من الـ Agents يمكنها التخطيط والتنفيذ والتعاون لتحقيق أهداف عالية المستوى. + + + اربط Agents بأي API أو قاعدة بيانات أو أداة محلية. + + + مصمم مع مراعاة الأمان والامتثال لعمليات نشر المؤسسات. + + + +## متى تستخدم Crews مقابل Flows + +**الإجابة المختصرة: استخدم كليهما.** + +لأي تطبيق جاهز للإنتاج، **ابدأ بـ Flow**. + +- **استخدم Flow** لتعريف الهيكل العام والحالة والمنطق لتطبيقك. +- **استخدم Crew** ضمن خطوة Flow عندما تحتاج فريقًا من الـ Agents لأداء مهمة معقدة محددة تتطلب استقلالية. + +| حالة الاستخدام | البنية المعمارية | +| :--- | :--- | +| **أتمتة بسيطة** | Flow واحد مع مهام Python | +| **بحث معقد** | Flow يدير الحالة -> Crew يجري البحث | +| **واجهة تطبيق خلفية** | Flow يعالج طلبات API -> Crew ينشئ المحتوى -> Flow يحفظ في قاعدة البيانات | + +## لماذا تختار CrewAI؟ + +- **تشغيل مستقل**: تتخذ الـ Agents قرارات ذكية بناءً على أدوارها وأدواتها المتاحة +- **تفاعل طبيعي**: تتواصل الـ Agents وتتعاون كأعضاء فريق بشري +- **تصميم قابل للتوسيع**: سهولة إضافة أدوات وأدوار وقدرات جديدة +- **جاهز للإنتاج**: مبني للموثوقية والتوسع في التطبيقات الواقعية +- **موجّه نحو الأمان**: مصمم مع مراعاة متطلبات أمان المؤسسات +- **كفاءة التكلفة**: محسّن لتقليل استخدام الرموز المميزة واستدعاءات API + +## هل أنت مستعد للبدء في البناء؟ + + + + تعلم كيفية إنشاء سير عمل منظمة قائمة على الأحداث مع تحكم دقيق في التنفيذ. + + + دليل تفصيلي لإنشاء فريق AI تعاوني يعمل معًا لحل المشكلات المعقدة. + + + + + + ابدأ مع CrewAI في بيئة التطوير الخاصة بك. + + + أنشئ Flow وشغّل طاقمًا بوكيل واحد وأنشئ تقريرًا من البداية للنهاية. + + + تواصل مع مطورين آخرين واحصل على المساعدة وشارك تجاربك مع CrewAI. + + diff --git a/docs/ar/learn/a2a-agent-delegation.mdx b/docs/ar/learn/a2a-agent-delegation.mdx new file mode 100644 index 000000000..d743d98fb --- /dev/null +++ b/docs/ar/learn/a2a-agent-delegation.mdx @@ -0,0 +1,87 @@ +--- +title: بروتوكول Agent-to-Agent (A2A) +description: الـ Agents تفوّض المهام إلى Agents A2A بعيدة و/أو تعمل كـ Agents خادم متوافقة مع A2A. +icon: network-wired +mode: "wide" +--- + +## تفويض Agent A2A + +يعامل CrewAI [بروتوكول A2A](https://a2a-protocol.org/latest/) كبنية تفويض أساسية، مما يمكّن الـ Agents من تفويض المهام وطلب المعلومات والتعاون مع Agents بعيدة، وكذلك العمل كـ Agents خادم متوافقة مع A2A. في وضع العميل، تختار الـ Agents تلقائيًا بين التنفيذ المحلي والتفويض البعيد بناءً على متطلبات المهمة. + +## كيف يعمل + +عندما يُهيَّأ Agent بقدرات A2A: + +1. يحلل الـ Agent كل مهمة +2. يقرر إما: + - معالجة المهمة مباشرة باستخدام قدراته الخاصة + - التفويض إلى Agent A2A بعيد للمعالجة المتخصصة +3. إذا فوّض، يتواصل الـ Agent مع Agent A2A البعيد عبر البروتوكول +4. تُعاد النتائج إلى سير عمل CrewAI + + + تفويض A2A يتطلب حزمة `a2a-sdk`. ثبّتها بـ: `uv add 'crewai[a2a]'` أو `pip install 'crewai[a2a]'` + + +## التهيئة الأساسية + + + `crewai.a2a.config.A2AConfig` مهمل وسيُزال في v2.0.0. استخدم `A2AClientConfig` للاتصال بـ Agents بعيدة و/أو `A2AServerConfig` لعرض الـ Agents كخوادم. + + +```python Code +from crewai import Agent, Crew, Task +from crewai.a2a import A2AClientConfig + +agent = Agent( + role="Research Coordinator", + goal="Coordinate research tasks efficiently", + backstory="Expert at delegating to specialized research agents", + llm="gpt-4o", + a2a=A2AClientConfig( + endpoint="https://example.com/.well-known/agent-card.json", + timeout=120, + max_turns=10 + ) +) + +task = Task( + description="Research the latest developments in quantum computing", + expected_output="A comprehensive research report", + agent=agent +) + +crew = Crew(agents=[agent], tasks=[task], verbose=True) +result = crew.kickoff() +``` + +## خيارات تهيئة العميل + +راجع الملف الإنجليزي الأصلي للحصول على القائمة الكاملة لمعاملات `A2AClientConfig` وخيارات المصادقة وآليات التحديث وتهيئة الخادم. + +## أفضل الممارسات + + + + هيّئ المهلات بناءً على أوقات استجابة Agent A2A المتوقعة. + + + + استخدم `max_turns` لمنع التبادل المفرط. + + + + عيّن `fail_fast=False` لبيئات الإنتاج مع عدة Agents. + + + + خزّن رموز المصادقة وبيانات الاعتماد كمتغيرات بيئة، ليس في الكود. + + + +## تعلم المزيد + +- [توثيق بروتوكول A2A](https://a2a-protocol.org) +- [تطبيقات A2A النموذجية](https://github.com/a2aproject/a2a-samples) +- [A2A Python SDK](https://github.com/a2aproject/a2a-python) diff --git a/docs/ar/learn/before-and-after-kickoff-hooks.mdx b/docs/ar/learn/before-and-after-kickoff-hooks.mdx new file mode 100644 index 000000000..0766a0f0d --- /dev/null +++ b/docs/ar/learn/before-and-after-kickoff-hooks.mdx @@ -0,0 +1,47 @@ +--- +title: خطافات قبل وبعد الانطلاق +description: تعلم كيفية استخدام خطافات قبل وبعد الانطلاق في CrewAI +mode: "wide" +--- + +يوفر CrewAI خطافات تتيح لك تنفيذ كود قبل وبعد انطلاق Crew. هذه الخطافات مفيدة لمعالجة المدخلات مسبقًا أو معالجة النتائج لاحقًا. + +## خطاف قبل الانطلاق + +يُنفَّذ خطاف قبل الانطلاق قبل أن يبدأ Crew مهامه. يتلقى قاموس المدخلات ويمكنه تعديله قبل تمريره إلى Crew. يمكنك استخدام هذا الخطاف لإعداد بيئتك أو تحميل البيانات اللازمة أو معالجة المدخلات مسبقًا. + +```python +from crewai import CrewBase +from crewai.project import before_kickoff + +@CrewBase +class MyCrew: + @before_kickoff + def prepare_data(self, inputs): + inputs['processed'] = True + return inputs +``` + +## خطاف بعد الانطلاق + +يُنفَّذ خطاف بعد الانطلاق بعد إتمام Crew مهامه. يتلقى كائن النتيجة الذي يحتوي على مخرجات تنفيذ Crew. هذا الخطاف مثالي لمعالجة النتائج لاحقًا مثل التسجيل أو تحويل البيانات أو التحليل الإضافي. + +```python +from crewai import CrewBase +from crewai.project import after_kickoff + +@CrewBase +class MyCrew: + @after_kickoff + def log_results(self, result): + print("Crew execution completed with result:", result) + return result +``` + +## استخدام كلا الخطافين + +يمكن استخدام كلا الخطافين معًا لتوفير عملية إعداد وتفكيك شاملة لتنفيذ Crew. وهما مفيدان بشكل خاص في الحفاظ على بنية كود نظيفة من خلال فصل المسؤوليات وتعزيز نمطية تنفيذات CrewAI. + +## الخلاصة + +توفر خطافات قبل وبعد الانطلاق في CrewAI طرقًا قوية للتفاعل مع دورة حياة تنفيذ Crew. من خلال فهم واستخدام هذه الخطافات، يمكنك تعزيز متانة ومرونة Agents الذكاء الاصطناعي بشكل كبير. diff --git a/docs/ar/learn/bring-your-own-agent.mdx b/docs/ar/learn/bring-your-own-agent.mdx new file mode 100644 index 000000000..d3b76446d --- /dev/null +++ b/docs/ar/learn/bring-your-own-agent.mdx @@ -0,0 +1,41 @@ +--- +title: أحضر Agent الخاص بك +description: تعلم كيفية إحضار Agents خاصة بك تعمل ضمن Crew. +icon: robots +mode: "wide" +--- + +قابلية التشغيل البيني مفهوم أساسي في CrewAI. يوضح هذا الدليل كيفية إحضار Agents خاصة بك تعمل ضمن Crew. + +## دليل المحوّلات لإحضار Agents الخاصة (Agents من LangGraph وOpenAI وغيرها...) + +نتطلب 3 محوّلات لتحويل أي Agent من أطر عمل مختلفة للعمل ضمن Crew. + +1. BaseAgentAdapter +2. BaseToolAdapter +3. BaseConverter + +## BaseAgentAdapter + +تعرّف هذه الفئة المجردة الواجهة المشتركة والوظائف التي يجب أن تنفذها جميع محوّلات الـ Agent. تمتد BaseAgent للحفاظ على التوافق مع إطار عمل CrewAI مع إضافة متطلبات خاصة بالمحوّل. + +الطرق المطلوبة: + +1. `def configure_tools` +2. `def configure_structured_output` + +## إنشاء محوّل خاص بك + +لدمج Agent من إطار عمل مختلف في CrewAI، تحتاج لإنشاء محوّل مخصص بوراثة `BaseAgentAdapter`. يعمل هذا المحوّل كطبقة توافق تترجم بين واجهات CrewAI والمتطلبات المحددة للـ Agent الخارجي. + +راجع الملف الإنجليزي الأصلي لأمثلة الكود التفصيلية لتنفيذ BaseAgentAdapter وBaseToolAdapter وBaseConverter. + +## محوّلات جاهزة للاستخدام + +نوفر محوّلات جاهزة للأطر التالية: +1. LangGraph +2. OpenAI Agents + +## تشغيل Crew مع Agents محوّلة: + +راجع الملف الإنجليزي الأصلي للحصول على مثال الكود الكامل الذي يوضح استخدام CrewAI Agent وOpenAI Agent Adapter وLangGraph Agent Adapter معًا في Crew واحد. diff --git a/docs/ar/learn/coding-agents.mdx b/docs/ar/learn/coding-agents.mdx new file mode 100644 index 000000000..f5f2f18d9 --- /dev/null +++ b/docs/ar/learn/coding-agents.mdx @@ -0,0 +1,80 @@ +--- +title: Agents البرمجة +description: تعلم كيفية تمكين Agents CrewAI من كتابة وتنفيذ الكود، واستكشف الميزات المتقدمة لوظائف محسّنة. +icon: rectangle-code +mode: "wide" +--- + +## مقدمة + +أصبح لدى CrewAI Agents القدرة القوية على كتابة وتنفيذ الكود، مما يعزز قدراتها في حل المشكلات بشكل كبير. هذه الميزة مفيدة بشكل خاص للمهام التي تتطلب حلولاً حسابية أو برمجية. + +## تمكين تنفيذ الكود + +لتمكين تنفيذ الكود لـ Agent، عيّن معامل `allow_code_execution` إلى `True` عند إنشاء الـ Agent. + +```python Code +from crewai import Agent + +coding_agent = Agent( + role="Senior Python Developer", + goal="Craft well-designed and thought-out code", + backstory="You are a senior Python developer with extensive experience in software architecture and best practices.", + allow_code_execution=True +) +``` + + +لاحظ أن معامل `allow_code_execution` يكون `False` افتراضيًا. + + +## اعتبارات مهمة + +1. **اختيار النموذج**: يُوصى بشدة باستخدام نماذج أكثر قدرة مثل Claude 3.5 Sonnet وGPT-4 عند تمكين تنفيذ الكود. + +2. **معالجة الأخطاء**: تتضمن ميزة تنفيذ الكود معالجة أخطاء. إذا أثار الكود المُنفَّذ استثناءً، سيتلقى الـ Agent رسالة الخطأ ويمكنه محاولة تصحيح الكود. يتحكم معامل `max_retry_limit` (الافتراضي 2) في الحد الأقصى لعدد المحاولات. + +3. **التبعيات**: لاستخدام ميزة تنفيذ الكود، تحتاج لتثبيت حزمة `crewai_tools`. + +## عملية تنفيذ الكود + + + + يحلل الـ Agent المهمة ويحدد أن تنفيذ الكود ضروري. + + + يصيغ كود Python اللازم لحل المشكلة. + + + يُرسَل الكود إلى أداة تنفيذ الكود الداخلية (`CodeInterpreterTool`). + + + يفسر الـ Agent النتيجة ويدمجها في استجابته أو يستخدمها لمزيد من حل المشكلات. + + + +## مثال استخدام + +```python Code +from crewai import Agent, Task, Crew + +coding_agent = Agent( + role="Python Data Analyst", + goal="Analyze data and provide insights using Python", + backstory="You are an experienced data analyst with strong Python skills.", + allow_code_execution=True +) + +data_analysis_task = Task( + description="Analyze the given dataset and calculate the average age of participants.", + agent=coding_agent +) + +analysis_crew = Crew( + agents=[coding_agent], + tasks=[data_analysis_task] +) + +result = analysis_crew.kickoff() +print(result) +``` diff --git a/docs/ar/learn/conditional-tasks.mdx b/docs/ar/learn/conditional-tasks.mdx new file mode 100644 index 000000000..818d72aac --- /dev/null +++ b/docs/ar/learn/conditional-tasks.mdx @@ -0,0 +1,14 @@ +--- +title: المهام الشرطية +description: تعلم كيفية استخدام المهام الشرطية في انطلاق crewAI +icon: diagram-subtask +mode: "wide" +--- + +## مقدمة + +تتيح المهام الشرطية في crewAI التكيف الديناميكي لسير العمل بناءً على نتائج المهام السابقة. تمكّن هذه الميزة القوية الـ Crews من اتخاذ قرارات وتنفيذ المهام بشكل انتقائي، مما يعزز مرونة وكفاءة عملياتك المدفوعة بالذكاء الاصطناعي. + +## مثال استخدام + +راجع الملف الإنجليزي الأصلي للحصول على مثال الكود الكامل الذي يوضح استخدام `ConditionalTask` مع دالة شرط `is_data_missing` للتحكم في تنفيذ المهام بناءً على مخرجات المهام السابقة. diff --git a/docs/ar/learn/create-custom-tools.mdx b/docs/ar/learn/create-custom-tools.mdx new file mode 100644 index 000000000..da82f5b45 --- /dev/null +++ b/docs/ar/learn/create-custom-tools.mdx @@ -0,0 +1,77 @@ +--- +title: إنشاء أدوات مخصصة +description: دليل شامل لصياغة واستخدام وإدارة الأدوات المخصصة ضمن إطار عمل CrewAI، بما في ذلك الوظائف الجديدة ومعالجة الأخطاء. +icon: hammer +mode: "wide" +--- + +## إنشاء واستخدام الأدوات في CrewAI + +يقدم هذا الدليل تعليمات مفصلة لإنشاء أدوات مخصصة لإطار عمل CrewAI وكيفية إدارة واستخدام هذه الأدوات بكفاءة، مع دمج أحدث الوظائف مثل تفويض الأدوات ومعالجة الأخطاء واستدعاء الأدوات الديناميكي. + + + **هل تريد نشر أداتك للمجتمع؟** إذا كنت تبني أداة يمكن أن تفيد الآخرين، اطلع على دليل [نشر أدوات مخصصة](/ar/guides/tools/publish-custom-tools) لتعلم كيفية تعبئة وتوزيع أداتك على PyPI. + + +### وراثة `BaseTool` + +لإنشاء أداة مخصصة، ورث من `BaseTool` وعرّف السمات الضرورية بما في ذلك `args_schema` للتحقق من المدخلات وطريقة `_run`. + +```python Code +from typing import Type +from crewai.tools import BaseTool +from pydantic import BaseModel, Field + +class MyToolInput(BaseModel): + """Input schema for MyCustomTool.""" + argument: str = Field(..., description="Description of the argument.") + +class MyCustomTool(BaseTool): + name: str = "Name of my tool" + description: str = "What this tool does. It's vital for effective utilization." + args_schema: Type[BaseModel] = MyToolInput + + def _run(self, argument: str) -> str: + return "Tool's result" +``` + +### استخدام مزخرف `tool` + +```python Code +from crewai.tools import tool + +@tool("Tool Name") +def my_simple_tool(question: str) -> str: + """Tool description for clarity.""" + return "Tool output" +``` + +### تعريف دالة تخزين مؤقت للأداة + +```python Code +@tool("Tool with Caching") +def cached_tool(argument: str) -> str: + """Tool functionality description.""" + return "Cacheable result" + +def my_cache_strategy(arguments: dict, result: str) -> bool: + return True if some_condition else False + +cached_tool.cache_function = my_cache_strategy +``` + +### إنشاء أدوات غير متزامنة + +يدعم CrewAI الأدوات غير المتزامنة لعمليات I/O غير المحجوبة. + +```python Code +import aiohttp +from crewai.tools import tool + +@tool("Async Web Fetcher") +async def fetch_webpage(url: str) -> str: + """Fetch content from a webpage asynchronously.""" + async with aiohttp.ClientSession() as session: + async with session.get(url) as response: + return await response.text() +``` diff --git a/docs/ar/learn/custom-llm.mdx b/docs/ar/learn/custom-llm.mdx new file mode 100644 index 000000000..a02222356 --- /dev/null +++ b/docs/ar/learn/custom-llm.mdx @@ -0,0 +1,55 @@ +--- +title: تنفيذ LLM مخصص +description: تعلم كيفية إنشاء تنفيذات LLM مخصصة في CrewAI. +icon: code +mode: "wide" +--- + +## نظرة عامة + +يدعم CrewAI تنفيذات LLM المخصصة من خلال فئة `BaseLLM` المجردة. يتيح لك ذلك دمج أي مزود LLM لا يحظى بدعم مدمج في LiteLLM، أو تنفيذ آليات مصادقة مخصصة. + +## بداية سريعة + +راجع الملف الإنجليزي الأصلي للحصول على تنفيذ LLM مخصص كامل يوضح طريقة `call()` المطلوبة والطرق الاختيارية مثل `supports_function_calling()` و`get_context_window_size()`. + +## استخدام LLM المخصص + +```python +from crewai import Agent, Task, Crew + +custom_llm = CustomLLM( + model="my-custom-model", + api_key="your-api-key", + endpoint="https://api.example.com/v1/chat/completions", + temperature=0.7 +) + +agent = Agent( + role="Research Assistant", + goal="Find and analyze information", + backstory="You are a research assistant.", + llm=custom_llm +) + +task = Task( + description="Research the latest developments in AI", + expected_output="A comprehensive summary", + agent=agent +) + +crew = Crew(agents=[agent], tasks=[task]) +result = crew.kickoff() +``` + +## الطرق المطلوبة + +### البنّاء: `__init__()` + +**مهم**: يجب استدعاء `super().__init__(model, temperature)` مع المعاملات المطلوبة. + +### الطريقة المجردة: `call()` + +طريقة `call()` هي قلب تنفيذ LLM. يجب أن تقبل الرسائل وتعيد استجابة نصية وتعالج الأدوات واستدعاء الدوال إذا كانت مدعومة. + +يغطي هذا الدليل أساسيات تنفيذ LLM مخصصة في CrewAI. diff --git a/docs/ar/learn/custom-manager-agent.mdx b/docs/ar/learn/custom-manager-agent.mdx new file mode 100644 index 000000000..c20f8a272 --- /dev/null +++ b/docs/ar/learn/custom-manager-agent.mdx @@ -0,0 +1,81 @@ +--- +title: Agent مدير مخصص +description: تعلم كيفية تعيين Agent مخصص كمدير في CrewAI، مما يوفر مزيدًا من التحكم في إدارة المهام والتنسيق. +icon: user-shield +mode: "wide" +--- + +# تعيين Agent محدد كمدير في CrewAI + +يتيح CrewAI للمستخدمين تعيين Agent محدد كمدير للـ Crew، مما يوفر مزيدًا من التحكم في إدارة المهام وتنسيقها. + +## استخدام سمة `manager_agent` + +تتيح لك سمة `manager_agent` تعريف Agent مخصص لإدارة الـ Crew. سيشرف هذا الـ Agent على العملية بأكملها لضمان إتمام المهام بكفاءة وبأعلى المعايير. + +```python Code +import os +from crewai import Agent, Task, Crew, Process + +researcher = Agent( + role="Researcher", + goal="Conduct thorough research and analysis on AI and AI agents", + backstory="You're an expert researcher...", + allow_delegation=False, +) + +writer = Agent( + role="Senior Writer", + goal="Create compelling content about AI and AI agents", + backstory="You're a senior writer...", + allow_delegation=False, +) + +task = Task( + description="Generate a list of 5 interesting ideas for an article...", + expected_output="5 bullet points, each with a paragraph and accompanying notes.", +) + +manager = Agent( + role="Project Manager", + goal="Efficiently manage the crew and ensure high-quality task completion", + backstory="You're an experienced project manager...", + allow_delegation=True, +) + +crew = Crew( + agents=[researcher, writer], + tasks=[task], + manager_agent=manager, + process=Process.hierarchical, +) + +result = crew.kickoff() +``` + +## فوائد Agent المدير المخصص + +- **تحكم محسّن**: تخصيص نهج الإدارة ليناسب الاحتياجات المحددة لمشروعك. +- **تنسيق محسّن**: ضمان تنسيق المهام وإدارتها بكفاءة من قبل Agent ذي خبرة. +- **إدارة قابلة للتخصيص**: تعريف أدوار ومسؤوليات إدارية تتماشى مع أهداف مشروعك. + +## تعيين LLM للمدير + +إذا كنت تستخدم العملية الهرمية ولا تريد تعيين Agent مدير مخصص، يمكنك تحديد نموذج اللغة للمدير: + +```python Code +from crewai import LLM + +manager_llm = LLM(model="gpt-4o") + +crew = Crew( + agents=[researcher, writer], + tasks=[task], + process=Process.hierarchical, + manager_llm=manager_llm +) +``` + + +يجب تعيين إما `manager_agent` أو `manager_llm` عند استخدام العملية الهرمية. + diff --git a/docs/ar/learn/customizing-agents.mdx b/docs/ar/learn/customizing-agents.mdx new file mode 100644 index 000000000..54ce5977c --- /dev/null +++ b/docs/ar/learn/customizing-agents.mdx @@ -0,0 +1,67 @@ +--- +title: تخصيص الـ Agents +description: دليل شامل لتخصيص الـ Agents لأدوار ومهام محددة وتخصيصات متقدمة ضمن إطار عمل CrewAI. +icon: user-pen +mode: "wide" +--- + +## السمات القابلة للتخصيص + +يعتمد بناء فريق CrewAI فعّال على القدرة على تخصيص Agents الذكاء الاصطناعي ديناميكيًا لتلبية المتطلبات الفريدة لأي مشروع. يغطي هذا القسم السمات الأساسية التي يمكنك تخصيصها. + +### السمات الرئيسية للتخصيص + +| السمة | الوصف | +|:-----------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------| +| **Role** | يحدد وظيفة الـ Agent ضمن Crew، مثل 'محلل' أو 'ممثل خدمة عملاء'. | +| **Goal** | يعرّف أهداف الـ Agent، متوافقة مع دوره ومهمة Crew الشاملة. | +| **Backstory** | يوفر عمقًا لشخصية الـ Agent، معززًا الدوافع والتفاعلات ضمن Crew. | +| **Tools** *(اختياري)* | يمثل القدرات أو الطرق التي يستخدمها الـ Agent للمهام. | +| **Cache** *(اختياري)* | يحدد ما إذا كان الـ Agent يجب أن يستخدم ذاكرة مؤقتة لاستخدام الأدوات. | +| **Max RPM** | يعيّن الحد الأقصى للطلبات في الدقيقة (`max_rpm`). | +| **Verbose** *(اختياري)* | يمكّن التسجيل التفصيلي للتصحيح والتحسين. | +| **Allow Delegation** *(اختياري)* | يتحكم في تفويض المهام لـ Agents أخرى، الافتراضي `False`. | +| **Max Iter** *(اختياري)* | يحد الحد الأقصى لعدد التكرارات (`max_iter`) لمهمة، الافتراضي 25. | + +## خيارات تخصيص متقدمة + +### تخصيص نموذج اللغة + +يمكن تخصيص الـ Agents بنماذج لغة محددة (`llm`) ونماذج لغة لاستدعاء الدوال (`function_calling_llm`)، مما يوفر تحكمًا متقدمًا في قدرات المعالجة وصنع القرار. + +## إعدادات الأداء والتصحيح + +- **وضع التفصيل**: يمكّن التسجيل التفصيلي لإجراءات الـ Agent. +- **حد RPM**: يعيّن الحد الأقصى للطلبات في الدقيقة. + +### مثال: تعيين أدوات لـ Agent + +```python Code +import os +from crewai import Agent +from crewai_tools import SerperDevTool + +os.environ["OPENAI_API_KEY"] = "Your Key" +os.environ["SERPER_API_KEY"] = "Your Key" + +search_tool = SerperDevTool() + +agent = Agent( + role='Research Analyst', + goal='Provide up-to-date market analysis', + backstory='An expert analyst with a keen eye for market trends.', + tools=[search_tool], + memory=True, + verbose=True, + max_rpm=None, + max_iter=25, +) +``` + +## التفويض والاستقلالية + +التحكم في قدرة الـ Agent على تفويض المهام أو طرح الأسئلة أمر حيوي لتخصيص استقلاليته وديناميكيات التعاون. افتراضيًا، سمة `allow_delegation` معيّنة على `False`. + +## الخلاصة + +تخصيص الـ Agents في CrewAI من خلال تعيين أدوارهم وأهدافهم وخلفياتهم وأدواتهم، إلى جانب خيارات متقدمة مثل تخصيص نموذج اللغة والذاكرة وإعدادات الأداء وتفضيلات التفويض، يجهّز فريق AI دقيق وقادر جاهز للتحديات المعقدة. diff --git a/docs/ar/learn/dalle-image-generation.mdx b/docs/ar/learn/dalle-image-generation.mdx new file mode 100644 index 000000000..0ab1c3754 --- /dev/null +++ b/docs/ar/learn/dalle-image-generation.mdx @@ -0,0 +1,52 @@ +--- +title: "إنشاء الصور باستخدام DALL-E" +description: "تعلم كيفية استخدام DALL-E لإنشاء صور مدعومة بالذكاء الاصطناعي في مشاريع CrewAI" +icon: "image" +mode: "wide" +--- + +يدعم CrewAI التكامل مع DALL-E من OpenAI، مما يتيح لـ Agents الذكاء الاصطناعي إنشاء صور كجزء من مهامهم. سيرشدك هذا الدليل عبر كيفية إعداد واستخدام أداة DALL-E في مشاريع CrewAI. + +## المتطلبات المسبقة + +- crewAI مثبّت (أحدث إصدار) +- مفتاح OpenAI API مع وصول إلى DALL-E + +## إعداد أداة DALL-E + + + + ```python + from crewai_tools import DallETool + ``` + + + + ```python + @agent + def researcher(self) -> Agent: + return Agent( + config=self.agents_config['researcher'], + tools=[SerperDevTool(), DallETool()], + allow_delegation=False, + verbose=True + ) + ``` + + + +## استخدام أداة DALL-E + +بمجرد إضافة أداة DALL-E إلى Agent، يمكنه إنشاء صور بناءً على مطالبات نصية. ستعيد الأداة رابط URL للصورة المُنشأة. + +## أفضل الممارسات + +1. **كن محددًا في مطالبات إنشاء الصور** للحصول على أفضل النتائج. +2. **ضع في اعتبارك وقت الإنشاء** - قد يستغرق إنشاء الصور بعض الوقت. +3. **اتبع سياسات الاستخدام** - التزم دائمًا بسياسات استخدام OpenAI عند إنشاء الصور. + +## استكشاف الأخطاء + +1. **تحقق من وصول API** - تأكد من أن مفتاح OpenAI API لديه وصول إلى DALL-E. +2. **توافق الإصدارات** - تأكد من استخدام أحدث إصدار من crewAI وcrewai-tools. +3. **تهيئة الأداة** - تحقق من إضافة أداة DALL-E بشكل صحيح لقائمة أدوات الـ Agent. diff --git a/docs/ar/learn/execution-hooks.mdx b/docs/ar/learn/execution-hooks.mdx new file mode 100644 index 000000000..1444eb58d --- /dev/null +++ b/docs/ar/learn/execution-hooks.mdx @@ -0,0 +1,86 @@ +--- +title: نظرة عامة على خطافات التنفيذ +description: فهم واستخدام خطافات التنفيذ في CrewAI للتحكم الدقيق في عمليات الـ Agent +mode: "wide" +--- + +توفر خطافات التنفيذ تحكمًا دقيقًا في سلوك وقت تشغيل Agents CrewAI. على عكس خطافات الانطلاق التي تعمل قبل وبعد تنفيذ Crew، تعترض خطافات التنفيذ عمليات محددة أثناء تنفيذ الـ Agent، مما يتيح لك تعديل السلوك وتنفيذ فحوصات أمان وإضافة مراقبة شاملة. + +## أنواع خطافات التنفيذ + +### 1. [خطافات استدعاء LLM](/learn/llm-hooks) + +التحكم ومراقبة تفاعلات نموذج اللغة: +- **قبل استدعاء LLM**: تعديل المطالبات، التحقق من المدخلات، بوابات الموافقة +- **بعد استدعاء LLM**: تحويل الاستجابات، تنقية المخرجات، تحديث سجل المحادثة + +### 2. [خطافات استدعاء الأدوات](/learn/tool-hooks) + +التحكم ومراقبة تنفيذ الأدوات: +- **قبل استدعاء الأداة**: تعديل المدخلات، التحقق من المعاملات، حظر العمليات الخطرة +- **بعد استدعاء الأداة**: تحويل النتائج، تنقية المخرجات، تسجيل تفاصيل التنفيذ + +## طرق تسجيل الخطافات + +### 1. خطافات بالمزخرفات (مُوصى بها) + +```python +from crewai.hooks import before_llm_call, after_llm_call, before_tool_call, after_tool_call + +@before_llm_call +def limit_iterations(context): + if context.iterations > 10: + return False + return None + +@after_llm_call +def sanitize_response(context): + if "API_KEY" in context.response: + return context.response.replace("API_KEY", "[REDACTED]") + return None + +@before_tool_call +def block_dangerous_tools(context): + if context.tool_name == "delete_database": + return False + return None +``` + +### 2. خطافات نطاق Crew + +```python +from crewai import CrewBase +from crewai.project import crew +from crewai.hooks import before_llm_call_crew, after_tool_call_crew + +@CrewBase +class MyProjCrew: + @before_llm_call_crew + def validate_inputs(self, context): + print(f"LLM call in {self.__class__.__name__}") + return None + + @after_tool_call_crew + def log_results(self, context): + print(f"Tool result: {context.tool_result[:50]}...") + return None +``` + +## أفضل الممارسات + +1. **اجعل الخطافات مركّزة** - كل خطاف يجب أن يكون له مسؤولية واحدة واضحة +2. **عالج الأخطاء بلطف** +3. **عدّل السياق في مكانه** +4. **استخدم تلميحات الأنواع** +5. **نظّف في الاختبارات** + +## التوثيق ذو الصلة + +- [خطافات استدعاء LLM](/learn/llm-hooks) +- [خطافات استدعاء الأدوات](/learn/tool-hooks) +- [خطافات قبل وبعد الانطلاق](/learn/before-and-after-kickoff-hooks) +- [التدخل البشري](/learn/human-in-the-loop) + +## الخلاصة + +توفر خطافات التنفيذ تحكمًا قويًا في سلوك وقت تشغيل الـ Agent. استخدمها لتنفيذ حواجز أمان وسير عمل موافقة ومراقبة شاملة ومنطق أعمال مخصص. diff --git a/docs/ar/learn/force-tool-output-as-result.mdx b/docs/ar/learn/force-tool-output-as-result.mdx new file mode 100644 index 000000000..8551e7680 --- /dev/null +++ b/docs/ar/learn/force-tool-output-as-result.mdx @@ -0,0 +1,45 @@ +--- +title: فرض مخرجات الأداة كنتيجة +description: تعلم كيفية فرض مخرجات الأداة كنتيجة لمهمة Agent في CrewAI. +icon: wrench-simple +mode: "wide" +--- + +## مقدمة + +في CrewAI، يمكنك فرض مخرجات أداة كنتيجة لمهمة Agent. هذه الميزة مفيدة عندما تريد التأكد من التقاط مخرجات الأداة وإعادتها كنتيجة للمهمة، متجنبًا أي تعديل من قبل الـ Agent أثناء تنفيذ المهمة. + +## فرض مخرجات الأداة كنتيجة + +لفرض مخرجات الأداة كنتيجة لمهمة Agent، تحتاج لتعيين معامل `result_as_answer` إلى `True` عند إضافة أداة إلى الـ Agent. + +```python Code +from crewai.agent import Agent +from my_tool import MyCustomTool + +coding_agent = Agent( + role="Data Scientist", + goal="Produce amazing reports on AI", + backstory="You work with data and AI", + tools=[MyCustomTool(result_as_answer=True)], + ) + +task_result = coding_agent.execute_task(task) +``` + +## سير العمل أثناء التنفيذ + + + + ينفذ الـ Agent المهمة باستخدام الأداة المقدمة. + + + تولّد الأداة المخرجات التي تُلتقط كنتيجة للمهمة. + + + قد يتأمل الـ Agent ويستخلص دروسًا من الأداة لكن لا يعدّل المخرجات. + + + تُعاد مخرجات الأداة كنتيجة للمهمة دون أي تعديلات. + + diff --git a/docs/ar/learn/hierarchical-process.mdx b/docs/ar/learn/hierarchical-process.mdx new file mode 100644 index 000000000..af783bdcd --- /dev/null +++ b/docs/ar/learn/hierarchical-process.mdx @@ -0,0 +1,76 @@ +--- +title: العملية الهرمية +description: دليل شامل لفهم وتطبيق العملية الهرمية ضمن مشاريع CrewAI. +icon: sitemap +mode: "wide" +--- + +## مقدمة + +تقدم العملية الهرمية في CrewAI نهجًا منظمًا لإدارة المهام، محاكاةً للتسلسلات الهرمية التنظيمية التقليدية للتفويض والتنفيذ الفعّال للمهام. + + + صُممت العملية الهرمية للاستفادة من نماذج متقدمة مثل GPT-4، مما يحسّن استخدام الرموز المميزة مع التعامل مع المهام المعقدة بكفاءة أكبر. + + +## نظرة عامة على العملية الهرمية + +افتراضيًا، تُدار المهام في CrewAI من خلال عملية متسلسلة. لكن اعتماد نهج هرمي يتيح تسلسلاً واضحًا في إدارة المهام، حيث يقوم Agent 'مدير' بتنسيق سير العمل وتفويض المهام والتحقق من النتائج. + +### الميزات الرئيسية + +- **تفويض المهام**: Agent مدير يوزّع المهام بين أعضاء Crew بناءً على أدوارهم وقدراتهم. +- **التحقق من النتائج**: يقيّم المدير النتائج لضمان استيفائها للمعايير المطلوبة. +- **سير عمل فعّال**: يحاكي الهياكل المؤسسية مقدمًا نهجًا منظمًا لإدارة المهام. + +## تنفيذ العملية الهرمية + +```python Code +from crewai import Crew, Process, Agent + +researcher = Agent( + role='Researcher', + goal='Conduct in-depth analysis', + backstory='Experienced data analyst with a knack for uncovering hidden trends.', +) +writer = Agent( + role='Writer', + goal='Create engaging content', + backstory='Creative writer passionate about storytelling in technical domains.', +) + +project_crew = Crew( + tasks=[...], + agents=[researcher, writer], + manager_llm="gpt-4o", + process=Process.hierarchical, + planning=True, +) +``` + +### استخدام Agent مدير مخصص + +```python +manager = Agent( + role="Project Manager", + goal="Efficiently manage the crew and ensure high-quality task completion", + backstory="You're an experienced project manager...", + allow_delegation=True, +) + +project_crew = Crew( + tasks=[...], + agents=[researcher, writer], + manager_agent=manager, + process=Process.hierarchical, + planning=True, +) +``` + + + لمزيد من التفاصيل حول إنشاء وتخصيص Agent مدير، اطلع على [توثيق Agent المدير المخصص](/ar/learn/custom-manager-agent). + + +## الخلاصة + +اعتماد العملية الهرمية في CrewAI مع التهيئات الصحيحة وفهم قدرات النظام يسهّل نهجًا منظمًا وفعّالاً لإدارة المشاريع. استفد من الميزات المتقدمة والتخصيصات لتكييف سير العمل لاحتياجاتك المحددة. diff --git a/docs/ar/learn/human-feedback-in-flows.mdx b/docs/ar/learn/human-feedback-in-flows.mdx new file mode 100644 index 000000000..11aeffcf6 --- /dev/null +++ b/docs/ar/learn/human-feedback-in-flows.mdx @@ -0,0 +1,98 @@ +--- +title: التغذية الراجعة البشرية في Flows +description: تعلم كيفية دمج التغذية الراجعة البشرية مباشرة في CrewAI Flows باستخدام مزخرف @human_feedback +icon: user-check +mode: "wide" +--- + +## نظرة عامة + + +يتطلب مزخرف `@human_feedback` إصدار **CrewAI 1.8.0 أو أحدث**. تأكد من تحديث تثبيتك قبل استخدام هذه الميزة. + + +يمكّن مزخرف `@human_feedback` سير العمل البشري في الحلقة (HITL) مباشرة ضمن CrewAI Flows. يتيح لك إيقاف تنفيذ Flow مؤقتًا وعرض المخرجات لإنسان للمراجعة وجمع تعليقاته واختياريًا التوجيه إلى مستمعين مختلفين بناءً على نتيجة التعليقات. + +هذا مفيد بشكل خاص لـ: + +- **ضمان الجودة**: مراجعة المحتوى المُنشأ بالذكاء الاصطناعي قبل استخدامه +- **بوابات القرار**: السماح للبشر باتخاذ قرارات حرجة في سير العمل الآلي +- **سير عمل الموافقة**: تنفيذ أنماط الموافقة/الرفض/المراجعة +- **التحسين التفاعلي**: جمع التعليقات لتحسين المخرجات تكراريًا + +## بداية سريعة + +```python Code +from crewai.flow.flow import Flow, start, listen +from crewai.flow.human_feedback import human_feedback + +class SimpleReviewFlow(Flow): + @start() + @human_feedback(message="Please review this content:") + def generate_content(self): + return "This is AI-generated content that needs review." + + @listen(generate_content) + def process_feedback(self, result): + print(f"Content: {result.output}") + print(f"Human said: {result.feedback}") + +flow = SimpleReviewFlow() +flow.kickoff() +``` + +## التوجيه مع emit + +عند تحديد `emit`، يصبح المزخرف موجّهًا. يُفسَّر التعليق البشري الحر بواسطة LLM ويُختزل إلى إحدى النتائج المحددة: + +```python Code +from crewai.flow.flow import Flow, start, listen, or_ +from crewai.flow.human_feedback import human_feedback + +class ReviewFlow(Flow): + @start() + def generate_content(self): + return "Draft blog post content here..." + + @human_feedback( + message="Do you approve this content for publication?", + emit=["approved", "rejected", "needs_revision"], + llm="gpt-4o-mini", + default_outcome="needs_revision", + ) + @listen(or_("generate_content", "needs_revision")) + def review_content(self): + return "Draft blog post content here..." + + @listen("approved") + def publish(self, result): + print(f"Publishing! User said: {result.feedback}") + + @listen("rejected") + def discard(self, result): + print(f"Discarding. Reason: {result.feedback}") +``` + +## التعلم من التغذية الراجعة + +معامل `learn=True` يمكّن حلقة تغذية راجعة بين المراجعين البشريين ونظام الذاكرة. عند تمكينه، يحسّن النظام مخرجاته تدريجيًا بالتعلم من التصحيحات البشرية السابقة. + +## أفضل الممارسات + +1. **اكتب رسائل طلب واضحة** +2. **اختر نتائج ذات معنى** +3. **وفّر دائمًا نتيجة افتراضية** +4. **استخدم سجل التعليقات لمسارات التدقيق** + +## التغذية الراجعة البشرية غير المتزامنة (غير محجوبة) + +استخدم معامل `provider` لتحديد استراتيجية جمع تعليقات مخصصة تتكامل مع أنظمة خارجية مثل Slack والبريد الإلكتروني وWebhooks وواجهات API. + +## التوثيق ذو الصلة + +- [نظرة عامة على Flows](/ar/concepts/flows) +- [إدارة حالة Flow](/ar/guides/flows/mastering-flow-state) +- [حفظ Flow](/ar/concepts/flows#persistence) +- [التوجيه مع @router](/ar/concepts/flows#router) +- [إدخال بشري عند التنفيذ](/ar/learn/human-input-on-execution) +- [الذاكرة](/ar/concepts/memory) diff --git a/docs/ar/learn/human-in-the-loop.mdx b/docs/ar/learn/human-in-the-loop.mdx new file mode 100644 index 000000000..69c5ea8a7 --- /dev/null +++ b/docs/ar/learn/human-in-the-loop.mdx @@ -0,0 +1,80 @@ +--- +title: "سير عمل التدخل البشري (HITL)" +description: "تعلم كيفية تنفيذ سير عمل التدخل البشري في CrewAI لتعزيز صنع القرار" +icon: "user-check" +mode: "wide" +--- + +التدخل البشري (HITL) هو نهج قوي يجمع بين الذكاء الاصطناعي والخبرة البشرية لتعزيز صنع القرار وتحسين نتائج المهام. يوفر CrewAI طرقًا متعددة لتنفيذ HITL حسب احتياجاتك. + +## اختيار نهج HITL + +يوفر CrewAI نهجين رئيسيين لتنفيذ سير عمل التدخل البشري: + +| النهج | الأنسب لـ | التكامل | الإصدار | +|----------|----------|-------------|---------| +| **قائم على Flow** (مزخرف `@human_feedback`) | التطوير المحلي، المراجعة عبر وحدة التحكم، سير العمل المتزامن | [التغذية الراجعة البشرية في Flows](/ar/learn/human-feedback-in-flows) | **1.8.0+** | +| **قائم على Webhook** (المؤسسات) | نشر الإنتاج، سير العمل غير المتزامن، التكاملات الخارجية (Slack، Teams، إلخ) | هذا الدليل | - | + + +إذا كنت تبني Flows وتريد إضافة خطوات مراجعة بشرية مع توجيه بناءً على التعليقات، اطلع على دليل [التغذية الراجعة البشرية في Flows](/ar/learn/human-feedback-in-flows) لمزخرف `@human_feedback`. + + +## إعداد سير عمل HITL القائم على Webhook + + + + أعدّ مهمتك مع تمكين إدخال بشري. + + + + عند تشغيل Crew، أدرج عنوان Webhook URL لإدخال بشري. + + + + بمجرد إتمام Crew المهمة التي تتطلب إدخالاً بشريًا، ستتلقى إشعار Webhook. + + + + سيتوقف النظام في حالة `Pending Human Input`. راجع مخرجات المهمة بعناية. + + + + استدعِ نقطة نهاية الاستئناف لـ Crew. + + + **مهم: يجب توفير عناوين Webhook URL مرة أخرى**: + يجب توفير نفس عناوين Webhook URL في استدعاء الاستئناف التي استخدمتها في استدعاء الانطلاق. + + + + + إذا قدمت تعليقات سلبية، سيعيد Crew محاولة المهمة مع سياق إضافي من تعليقاتك. + + + + عند إرسال تعليقات إيجابية، سيستمر التنفيذ إلى الخطوات التالية. + + + +## أفضل الممارسات + +- **كن محددًا**: قدم تعليقات واضحة وقابلة للتنفيذ +- **ابقَ ذا صلة**: أدرج فقط معلومات تساعد في تحسين تنفيذ المهمة +- **كن في الوقت المناسب**: استجب لمطالبات HITL بسرعة لتجنب تأخير سير العمل +- **راجع بعناية**: تحقق من تعليقاتك قبل الإرسال لضمان الدقة + +## حالات الاستخدام الشائعة + +سير عمل HITL مفيدة بشكل خاص لـ: +- ضمان الجودة والتحقق +- سيناريوهات صنع القرار المعقدة +- العمليات الحساسة أو عالية المخاطر +- المهام الإبداعية التي تتطلب حكمًا بشريًا +- مراجعات الامتثال والتنظيم + +## ميزات المؤسسات + + + يوفر CrewAI Enterprise نظام إدارة HITL شامل لـ Flows مع مراجعة داخل المنصة وتعيين المستجيبين والأذونات وسياسات التصعيد وإدارة SLA والتوجيه الديناميكي والتحليلات الكاملة. [تعلم المزيد](/ar/enterprise/features/flow-hitl-management) + diff --git a/docs/ar/learn/human-input-on-execution.mdx b/docs/ar/learn/human-input-on-execution.mdx new file mode 100644 index 000000000..756f170a0 --- /dev/null +++ b/docs/ar/learn/human-input-on-execution.mdx @@ -0,0 +1,99 @@ +--- +title: الإدخال البشري أثناء التنفيذ +description: دمج CrewAI مع الإدخال البشري أثناء التنفيذ في عمليات اتخاذ القرارات المعقدة والاستفادة الكاملة من إمكانيات خصائص وأدوات الوكيل. +icon: user-plus +mode: "wide" +--- + +## الإدخال البشري في تنفيذ الوكيل + +يُعد الإدخال البشري أمراً بالغ الأهمية في العديد من سيناريوهات تنفيذ الوكلاء، حيث يسمح للوكلاء بطلب معلومات إضافية أو توضيحات عند الضرورة. +هذه الميزة مفيدة بشكل خاص في عمليات اتخاذ القرارات المعقدة أو عندما يحتاج الوكلاء إلى مزيد من التفاصيل لإكمال مهمة بفعالية. + +## استخدام الإدخال البشري مع CrewAI + +لدمج الإدخال البشري في تنفيذ الوكيل، قم بتعيين علامة `human_input` في تعريف المهمة. عند تفعيلها، يطلب الوكيل من المستخدم إدخالاً قبل تقديم إجابته النهائية. +يمكن أن يوفر هذا الإدخال سياقاً إضافياً، أو يوضح الغموض، أو يتحقق من مخرجات الوكيل. + +### مثال: + +```shell +pip install crewai +``` + +```python Code +import os +from crewai import Agent, Task, Crew +from crewai_tools import SerperDevTool + +os.environ["SERPER_API_KEY"] = "Your Key" # serper.dev API key +os.environ["OPENAI_API_KEY"] = "Your Key" + +# Loading Tools +search_tool = SerperDevTool() + +# Define your agents with roles, goals, tools, and additional attributes +researcher = Agent( + role='Senior Research Analyst', + goal='Uncover cutting-edge developments in AI and data science', + backstory=( + "You are a Senior Research Analyst at a leading tech think tank. " + "Your expertise lies in identifying emerging trends and technologies in AI and data science. " + "You have a knack for dissecting complex data and presenting actionable insights." + ), + verbose=True, + allow_delegation=False, + tools=[search_tool] +) +writer = Agent( + role='Tech Content Strategist', + goal='Craft compelling content on tech advancements', + backstory=( + "You are a renowned Tech Content Strategist, known for your insightful and engaging articles on technology and innovation. " + "With a deep understanding of the tech industry, you transform complex concepts into compelling narratives." + ), + verbose=True, + allow_delegation=True, + tools=[search_tool], + cache=False, # Disable cache for this agent +) + +# Create tasks for your agents +task1 = Task( + description=( + "Conduct a comprehensive analysis of the latest advancements in AI in 2025. " + "Identify key trends, breakthrough technologies, and potential industry impacts. " + "Compile your findings in a detailed report. " + "Make sure to check with a human if the draft is good before finalizing your answer." + ), + expected_output='A comprehensive full report on the latest AI advancements in 2025, leave nothing out', + agent=researcher, + human_input=True +) + +task2 = Task( + description=( + "Using the insights from the researcher\'s report, develop an engaging blog post that highlights the most significant AI advancements. " + "Your post should be informative yet accessible, catering to a tech-savvy audience. " + "Aim for a narrative that captures the essence of these breakthroughs and their implications for the future." + ), + expected_output='A compelling 3 paragraphs blog post formatted as markdown about the latest AI advancements in 2025', + agent=writer, + human_input=True +) + +# Instantiate your crew with a sequential process +crew = Crew( + agents=[researcher, writer], + tasks=[task1, task2], + verbose=True, + memory=True, + planning=True # Enable planning feature for the crew +) + +# Get your crew to work! +result = crew.kickoff() + +print("######################") +print(result) +``` diff --git a/docs/ar/learn/kickoff-async.mdx b/docs/ar/learn/kickoff-async.mdx new file mode 100644 index 000000000..dfe446ba0 --- /dev/null +++ b/docs/ar/learn/kickoff-async.mdx @@ -0,0 +1,306 @@ +--- +title: تشغيل الطاقم بشكل غير متزامن +description: تشغيل الطاقم بشكل غير متزامن +icon: rocket-launch +mode: "wide" +--- + +## مقدمة + +يوفر CrewAI القدرة على تشغيل طاقم بشكل غير متزامن، مما يتيح لك بدء تنفيذ الطاقم بطريقة غير حاجبة. +هذه الميزة مفيدة بشكل خاص عندما تريد تشغيل عدة أطقم بشكل متزامن أو عندما تحتاج إلى أداء مهام أخرى أثناء تنفيذ الطاقم. + +يقدم CrewAI نهجين للتنفيذ غير المتزامن: + +| الطريقة | النوع | الوصف | +|--------|------|-------------| +| `akickoff()` | غير متزامن أصلي | async/await أصلي عبر سلسلة التنفيذ بالكامل | +| `kickoff_async()` | قائم على الخيوط | يغلف التنفيذ المتزامن في `asyncio.to_thread` | + + +لأحمال العمل عالية التزامن، يُوصى باستخدام `akickoff()` لأنه يستخدم async أصلي لتنفيذ المهام وعمليات الذاكرة واسترجاع المعرفة. + + +## التنفيذ غير المتزامن الأصلي مع `akickoff()` + +توفر طريقة `akickoff()` تنفيذاً غير متزامن أصلياً حقيقياً، باستخدام async/await عبر سلسلة التنفيذ بالكامل بما في ذلك تنفيذ المهام وعمليات الذاكرة واستعلامات المعرفة. + +### توقيع الطريقة + +```python Code +async def akickoff(self, inputs: dict) -> CrewOutput: +``` + +### المعاملات + +- `inputs` (dict): قاموس يحتوي على بيانات الإدخال المطلوبة للمهام. + +### القيمة المُرجعة + +- `CrewOutput`: كائن يمثل نتيجة تنفيذ الطاقم. + +### مثال: تنفيذ طاقم غير متزامن أصلي + +```python Code +import asyncio +from crewai import Crew, Agent, Task + +# Create an agent +coding_agent = Agent( + role="Python Data Analyst", + goal="Analyze data and provide insights using Python", + backstory="You are an experienced data analyst with strong Python skills.", + allow_code_execution=True +) + +# Create a task +data_analysis_task = Task( + description="Analyze the given dataset and calculate the average age of participants. Ages: {ages}", + agent=coding_agent, + expected_output="The average age of the participants." +) + +# Create a crew +analysis_crew = Crew( + agents=[coding_agent], + tasks=[data_analysis_task] +) + +# Native async execution +async def main(): + result = await analysis_crew.akickoff(inputs={"ages": [25, 30, 35, 40, 45]}) + print("Crew Result:", result) + +asyncio.run(main()) +``` + +### مثال: عدة أطقم غير متزامنة أصلية + +تشغيل عدة أطقم بشكل متزامن باستخدام `asyncio.gather()` مع async أصلي: + +```python Code +import asyncio +from crewai import Crew, Agent, Task + +coding_agent = Agent( + role="Python Data Analyst", + goal="Analyze data and provide insights using Python", + backstory="You are an experienced data analyst with strong Python skills.", + allow_code_execution=True +) + +task_1 = Task( + description="Analyze the first dataset and calculate the average age. Ages: {ages}", + agent=coding_agent, + expected_output="The average age of the participants." +) + +task_2 = Task( + description="Analyze the second dataset and calculate the average age. Ages: {ages}", + agent=coding_agent, + expected_output="The average age of the participants." +) + +crew_1 = Crew(agents=[coding_agent], tasks=[task_1]) +crew_2 = Crew(agents=[coding_agent], tasks=[task_2]) + +async def main(): + results = await asyncio.gather( + crew_1.akickoff(inputs={"ages": [25, 30, 35, 40, 45]}), + crew_2.akickoff(inputs={"ages": [20, 22, 24, 28, 30]}) + ) + + for i, result in enumerate(results, 1): + print(f"Crew {i} Result:", result) + +asyncio.run(main()) +``` + +### مثال: async أصلي لمدخلات متعددة + +استخدم `akickoff_for_each()` لتنفيذ طاقمك على مدخلات متعددة بشكل متزامن مع async أصلي: + +```python Code +import asyncio +from crewai import Crew, Agent, Task + +coding_agent = Agent( + role="Python Data Analyst", + goal="Analyze data and provide insights using Python", + backstory="You are an experienced data analyst with strong Python skills.", + allow_code_execution=True +) + +data_analysis_task = Task( + description="Analyze the dataset and calculate the average age. Ages: {ages}", + agent=coding_agent, + expected_output="The average age of the participants." +) + +analysis_crew = Crew( + agents=[coding_agent], + tasks=[data_analysis_task] +) + +async def main(): + datasets = [ + {"ages": [25, 30, 35, 40, 45]}, + {"ages": [20, 22, 24, 28, 30]}, + {"ages": [30, 35, 40, 45, 50]} + ] + + results = await analysis_crew.akickoff_for_each(datasets) + + for i, result in enumerate(results, 1): + print(f"Dataset {i} Result:", result) + +asyncio.run(main()) +``` + +## التنفيذ غير المتزامن القائم على الخيوط مع `kickoff_async()` + +توفر طريقة `kickoff_async()` تنفيذاً غير متزامن عن طريق تغليف `kickoff()` المتزامن في خيط. هذا مفيد للتكامل البسيط مع async أو للتوافق مع الإصدارات السابقة. + +### توقيع الطريقة + +```python Code +async def kickoff_async(self, inputs: dict) -> CrewOutput: +``` + +### المعاملات + +- `inputs` (dict): قاموس يحتوي على بيانات الإدخال المطلوبة للمهام. + +### القيمة المُرجعة + +- `CrewOutput`: كائن يمثل نتيجة تنفيذ الطاقم. + +### مثال: تنفيذ غير متزامن قائم على الخيوط + +```python Code +import asyncio +from crewai import Crew, Agent, Task + +coding_agent = Agent( + role="Python Data Analyst", + goal="Analyze data and provide insights using Python", + backstory="You are an experienced data analyst with strong Python skills.", + allow_code_execution=True +) + +data_analysis_task = Task( + description="Analyze the given dataset and calculate the average age of participants. Ages: {ages}", + agent=coding_agent, + expected_output="The average age of the participants." +) + +analysis_crew = Crew( + agents=[coding_agent], + tasks=[data_analysis_task] +) + +async def async_crew_execution(): + result = await analysis_crew.kickoff_async(inputs={"ages": [25, 30, 35, 40, 45]}) + print("Crew Result:", result) + +asyncio.run(async_crew_execution()) +``` + +### مثال: عدة أطقم غير متزامنة قائمة على الخيوط + +```python Code +import asyncio +from crewai import Crew, Agent, Task + +coding_agent = Agent( + role="Python Data Analyst", + goal="Analyze data and provide insights using Python", + backstory="You are an experienced data analyst with strong Python skills.", + allow_code_execution=True +) + +task_1 = Task( + description="Analyze the first dataset and calculate the average age of participants. Ages: {ages}", + agent=coding_agent, + expected_output="The average age of the participants." +) + +task_2 = Task( + description="Analyze the second dataset and calculate the average age of participants. Ages: {ages}", + agent=coding_agent, + expected_output="The average age of the participants." +) + +crew_1 = Crew(agents=[coding_agent], tasks=[task_1]) +crew_2 = Crew(agents=[coding_agent], tasks=[task_2]) + +async def async_multiple_crews(): + result_1 = crew_1.kickoff_async(inputs={"ages": [25, 30, 35, 40, 45]}) + result_2 = crew_2.kickoff_async(inputs={"ages": [20, 22, 24, 28, 30]}) + + results = await asyncio.gather(result_1, result_2) + + for i, result in enumerate(results, 1): + print(f"Crew {i} Result:", result) + +asyncio.run(async_multiple_crews()) +``` + +## البث غير المتزامن + +تدعم كلتا الطريقتين غير المتزامنتين البث عند تعيين `stream=True` على الطاقم: + +```python Code +import asyncio +from crewai import Crew, Agent, Task + +agent = Agent( + role="Researcher", + goal="Research and summarize topics", + backstory="You are an expert researcher." +) + +task = Task( + description="Research the topic: {topic}", + agent=agent, + expected_output="A comprehensive summary of the topic." +) + +crew = Crew( + agents=[agent], + tasks=[task], + stream=True # Enable streaming +) + +async def main(): + streaming_output = await crew.akickoff(inputs={"topic": "AI trends in 2024"}) + + # Async iteration over streaming chunks + async for chunk in streaming_output: + print(f"Chunk: {chunk.content}") + + # Access final result after streaming completes + result = streaming_output.result + print(f"Final result: {result.raw}") + +asyncio.run(main()) +``` + +## حالات الاستخدام المحتملة + +- **توليد المحتوى بالتوازي**: تشغيل عدة أطقم مستقلة بشكل غير متزامن، كل منها مسؤول عن توليد محتوى حول مواضيع مختلفة. على سبيل المثال، قد يبحث طاقم ويصوغ مقالاً عن اتجاهات الذكاء الاصطناعي، بينما يولد طاقم آخر منشورات وسائل التواصل الاجتماعي حول إطلاق منتج جديد. + +- **مهام أبحاث السوق المتزامنة**: إطلاق عدة أطقم بشكل غير متزامن لإجراء أبحاث السوق بالتوازي. قد يحلل طاقم اتجاهات الصناعة، بينما يفحص آخر استراتيجيات المنافسين، ويقيّم ثالث مشاعر المستهلكين. + +- **وحدات تخطيط السفر المستقلة**: تنفيذ أطقم منفصلة للتخطيط المستقل لجوانب مختلفة من رحلة. قد يتعامل طاقم مع خيارات الرحلات الجوية، وآخر مع الإقامة، وثالث يخطط للأنشطة. + +## الاختيار بين `akickoff()` و `kickoff_async()` + +| الميزة | `akickoff()` | `kickoff_async()` | +|---------|--------------|-------------------| +| نموذج التنفيذ | async/await أصلي | غلاف قائم على الخيوط | +| تنفيذ المهام | غير متزامن مع `aexecute_sync()` | متزامن في مجمع الخيوط | +| عمليات الذاكرة | غير متزامنة | متزامنة في مجمع الخيوط | +| استرجاع المعرفة | غير متزامن | متزامن في مجمع الخيوط | +| الأفضل لـ | أحمال العمل عالية التزامن والمرتبطة بالإدخال/الإخراج | التكامل البسيط مع async | +| دعم البث | نعم | نعم | diff --git a/docs/ar/learn/kickoff-for-each.mdx b/docs/ar/learn/kickoff-for-each.mdx new file mode 100644 index 000000000..a827799b0 --- /dev/null +++ b/docs/ar/learn/kickoff-for-each.mdx @@ -0,0 +1,54 @@ +--- +title: تشغيل الطاقم لكل عنصر +description: تشغيل الطاقم لكل عنصر في قائمة +icon: at +mode: "wide" +--- + +## مقدمة + +يوفر CrewAI القدرة على تشغيل طاقم لكل عنصر في قائمة، مما يتيح لك تنفيذ الطاقم لكل عنصر في القائمة. +هذه الميزة مفيدة بشكل خاص عندما تحتاج إلى تنفيذ نفس مجموعة المهام لعناصر متعددة. + +## تشغيل طاقم لكل عنصر + +لتشغيل طاقم لكل عنصر في قائمة، استخدم طريقة `kickoff_for_each()`. +تنفذ هذه الطريقة الطاقم لكل عنصر في القائمة، مما يتيح لك معالجة عناصر متعددة بكفاءة. + +إليك مثالاً على كيفية تشغيل طاقم لكل عنصر في قائمة: + +```python Code +from crewai import Crew, Agent, Task + +# Create an agent with code execution enabled +coding_agent = Agent( + role="Python Data Analyst", + goal="Analyze data and provide insights using Python", + backstory="You are an experienced data analyst with strong Python skills.", + allow_code_execution=True +) + +# Create a task that requires code execution +data_analysis_task = Task( + description="Analyze the given dataset and calculate the average age of participants. Ages: {ages}", + agent=coding_agent, + expected_output="The average age calculated from the dataset" +) + +# Create a crew and add the task +analysis_crew = Crew( + agents=[coding_agent], + tasks=[data_analysis_task], + verbose=True, + memory=False +) + +datasets = [ + { "ages": [25, 30, 35, 40, 45] }, + { "ages": [20, 25, 30, 35, 40] }, + { "ages": [30, 35, 40, 45, 50] } +] + +# Execute the crew +result = analysis_crew.kickoff_for_each(inputs=datasets) +``` diff --git a/docs/ar/learn/litellm-removal-guide.mdx b/docs/ar/learn/litellm-removal-guide.mdx new file mode 100644 index 000000000..b0e81d919 --- /dev/null +++ b/docs/ar/learn/litellm-removal-guide.mdx @@ -0,0 +1,358 @@ +--- +title: استخدام CrewAI بدون LiteLLM +description: كيفية استخدام CrewAI مع التكاملات الأصلية للمزودين وإزالة اعتمادية LiteLLM من مشروعك. +icon: shield-check +mode: "wide" +--- + +## نظرة عامة + +يدعم CrewAI مسارين للاتصال بمزودي LLM: + +1. **التكاملات الأصلية** — اتصالات SDK مباشرة مع OpenAI وAnthropic وGoogle Gemini وAzure OpenAI وAWS Bedrock +2. **LiteLLM كاحتياط** — طبقة ترجمة تدعم أكثر من 100 مزود إضافي + +يشرح هذا الدليل كيفية استخدام CrewAI حصرياً مع التكاملات الأصلية للمزودين، مع إزالة أي اعتمادية على LiteLLM. + + + تم عزل حزمة `litellm` على PyPI بسبب حادث أمني/موثوقية. إذا كنت تعتمد على مزودين يحتاجون LiteLLM، يجب عليك الانتقال إلى التكاملات الأصلية. توفر لك تكاملات CrewAI الأصلية الوظائف الكاملة بدون LiteLLM. + + +## لماذا إزالة LiteLLM؟ + +- **تقليل سطح الاعتماديات** — حزم أقل تعني مخاطر أقل محتملة في سلسلة التوريد +- **أداء أفضل** — تتواصل حزم SDK الأصلية مباشرة مع واجهات برمجة تطبيقات المزودين، مما يلغي طبقة الترجمة +- **تصحيح أخطاء أبسط** — طبقة تجريد واحدة أقل بين كودك والمزود +- **حجم تثبيت أصغر** — يجلب LiteLLM العديد من الاعتماديات العابرة + +## المزودون الأصليون (لا يحتاجون LiteLLM) + +هؤلاء المزودون يستخدمون حزم SDK الخاصة بهم ويعملون بدون تثبيت LiteLLM: + + + + GPT-4o، GPT-4o-mini، o1، o3-mini، والمزيد. + ```bash + uv add "crewai[openai]" + ``` + + + Claude Sonnet، Claude Haiku، والمزيد. + ```bash + uv add "crewai[anthropic]" + ``` + + + Gemini 2.0 Flash، Gemini 2.0 Pro، والمزيد. + ```bash + uv add "crewai[gemini]" + ``` + + + نماذج OpenAI المستضافة على Azure. + ```bash + uv add "crewai[azure]" + ``` + + + Claude، Llama، Titan، والمزيد عبر AWS. + ```bash + uv add "crewai[bedrock]" + ``` + + + + + إذا كنت تستخدم المزودين الأصليين فقط، فلن تحتاج **أبداً** لتثبيت `crewai[litellm]`. حزمة `crewai` الأساسية بالإضافة إلى الإضافة الخاصة بالمزود الذي اخترته هي كل ما تحتاجه. + + +## كيفية التحقق مما إذا كنت تستخدم LiteLLM + +### تحقق من سلاسل النماذج الخاصة بك + +إذا كان كودك يستخدم بادئات النماذج هذه، فأنت تمرر عبر LiteLLM: + +| البادئة | المزود | يستخدم LiteLLM؟ | +|--------|----------|---------------| +| `ollama/` | Ollama | ✅ نعم | +| `groq/` | Groq | ✅ نعم | +| `together_ai/` | Together AI | ✅ نعم | +| `mistral/` | Mistral | ✅ نعم | +| `cohere/` | Cohere | ✅ نعم | +| `huggingface/` | Hugging Face | ✅ نعم | +| `openai/` | OpenAI | ❌ أصلي | +| `anthropic/` | Anthropic | ❌ أصلي | +| `gemini/` | Google Gemini | ❌ أصلي | +| `azure/` | Azure OpenAI | ❌ أصلي | +| `bedrock/` | AWS Bedrock | ❌ أصلي | + +### تحقق مما إذا كان LiteLLM مثبتاً + +```bash +# Using pip +pip show litellm + +# Using uv +uv pip show litellm +``` + +إذا أرجع الأمر معلومات الحزمة، فإن LiteLLM مثبت في بيئتك. + +### تحقق من اعتمادياتك + +انظر إلى ملف `pyproject.toml` الخاص بك بحثاً عن `crewai[litellm]`: + +```toml +# If you see this, you have LiteLLM as a dependency +dependencies = [ + "crewai[litellm]>=0.100.0", # ← Uses LiteLLM +] + +# Change to a native provider extra instead +dependencies = [ + "crewai[openai]>=0.100.0", # ← Native, no LiteLLM +] +``` + +## دليل الانتقال + +### الخطوة 1: حدد مزودك الحالي + +ابحث عن جميع استدعاءات `LLM()` وسلاسل النماذج في كودك: + +```bash +# Search your codebase for LLM model strings +grep -r "LLM(" --include="*.py" . +grep -r "llm=" --include="*.yaml" . +grep -r "llm:" --include="*.yaml" . +``` + +### الخطوة 2: انتقل إلى مزود أصلي + + + + ```python + from crewai import LLM + + # Before (LiteLLM): + # llm = LLM(model="groq/llama-3.1-70b") + + # After (Native): + llm = LLM(model="openai/gpt-4o") + ``` + + ```bash + # Install + uv add "crewai[openai]" + + # Set your API key + export OPENAI_API_KEY="sk-..." + ``` + + + ```python + from crewai import LLM + + # Before (LiteLLM): + # llm = LLM(model="together_ai/meta-llama/Meta-Llama-3.1-70B") + + # After (Native): + llm = LLM(model="anthropic/claude-sonnet-4-20250514") + ``` + + ```bash + # Install + uv add "crewai[anthropic]" + + # Set your API key + export ANTHROPIC_API_KEY="sk-ant-..." + ``` + + + ```python + from crewai import LLM + + # Before (LiteLLM): + # llm = LLM(model="mistral/mistral-large-latest") + + # After (Native): + llm = LLM(model="gemini/gemini-2.0-flash") + ``` + + ```bash + # Install + uv add "crewai[gemini]" + + # Set your API key + export GEMINI_API_KEY="..." + ``` + + + ```python + from crewai import LLM + + # After (Native): + llm = LLM( + model="azure/your-deployment-name", + api_key="your-azure-api-key", + base_url="https://your-resource.openai.azure.com", + api_version="2024-06-01" + ) + ``` + + ```bash + # Install + uv add "crewai[azure]" + ``` + + + ```python + from crewai import LLM + + # After (Native): + llm = LLM( + model="bedrock/anthropic.claude-3-5-sonnet-20241022-v2:0", + aws_region_name="us-east-1" + ) + ``` + + ```bash + # Install + uv add "crewai[bedrock]" + + # Configure AWS credentials + export AWS_ACCESS_KEY_ID="..." + export AWS_SECRET_ACCESS_KEY="..." + export AWS_DEFAULT_REGION="us-east-1" + ``` + + + +### الخطوة 3: الاحتفاظ بـ Ollama بدون LiteLLM + +إذا كنت تستخدم Ollama وتريد الاستمرار في استخدامه، يمكنك الاتصال عبر واجهة برمجة تطبيقات Ollama المتوافقة مع OpenAI: + +```python +from crewai import LLM + +# Before (LiteLLM): +# llm = LLM(model="ollama/llama3") + +# After (OpenAI-compatible mode, no LiteLLM needed): +llm = LLM( + model="openai/llama3", + base_url="http://localhost:11434/v1", + api_key="ollama" # Ollama doesn't require a real API key +) +``` + + + العديد من خوادم الاستدلال المحلية (Ollama، vLLM، LM Studio، llama.cpp) توفر واجهة برمجة تطبيقات متوافقة مع OpenAI. يمكنك استخدام بادئة `openai/` مع `base_url` مخصص للاتصال بأي منها بشكل أصلي. + + +### الخطوة 4: تحديث إعدادات YAML + +```yaml +# Before (LiteLLM providers): +researcher: + role: Research Specialist + goal: Conduct research + backstory: A dedicated researcher + llm: groq/llama-3.1-70b # ← LiteLLM + +# After (Native provider): +researcher: + role: Research Specialist + goal: Conduct research + backstory: A dedicated researcher + llm: openai/gpt-4o # ← Native +``` + +### الخطوة 5: إزالة LiteLLM + +بمجرد انتقال جميع مراجع النماذج الخاصة بك: + +```bash +# Remove litellm from your project +uv remove litellm + +# Or if using pip +pip uninstall litellm + +# Update your pyproject.toml: change crewai[litellm] to your provider extra +# e.g., crewai[openai], crewai[anthropic], crewai[gemini] +``` + +### الخطوة 6: التحقق + +شغّل مشروعك وتأكد من أن كل شيء يعمل: + +```bash +# Run your crew +crewai run + +# Or run your tests +uv run pytest +``` + +## مرجع سريع: خريطة سلاسل النماذج + +فيما يلي مسارات الانتقال الشائعة من المزودين المعتمدين على LiteLLM إلى المزودين الأصليين: + +```python +from crewai import LLM + +# ─── LiteLLM providers → Native alternatives ──────────────────── + +# Groq → OpenAI or Anthropic +# llm = LLM(model="groq/llama-3.1-70b") +llm = LLM(model="openai/gpt-4o-mini") # Fast & affordable +llm = LLM(model="anthropic/claude-haiku-3-5") # Fast & affordable + +# Together AI → OpenAI or Gemini +# llm = LLM(model="together_ai/meta-llama/Meta-Llama-3.1-70B") +llm = LLM(model="openai/gpt-4o") # High quality +llm = LLM(model="gemini/gemini-2.0-flash") # Fast & capable + +# Mistral → Anthropic or OpenAI +# llm = LLM(model="mistral/mistral-large-latest") +llm = LLM(model="anthropic/claude-sonnet-4-20250514") # High quality + +# Ollama → OpenAI-compatible (keep using local models) +# llm = LLM(model="ollama/llama3") +llm = LLM( + model="openai/llama3", + base_url="http://localhost:11434/v1", + api_key="ollama" +) +``` + +## الأسئلة الشائعة + + + + لا، إذا كنت تستخدم أحد المزودين الخمسة المدعومين أصلياً (OpenAI، Anthropic، Gemini، Azure، Bedrock). تدعم هذه التكاملات الأصلية جميع ميزات CrewAI بما في ذلك البث واستدعاء الأدوات والمخرجات المنظمة والمزيد. ستفقد فقط الوصول إلى المزودين المتاحين حصرياً عبر LiteLLM (مثل Groq وTogether AI وMistral كمزودين من الدرجة الأولى). + + + نعم. ثبّت إضافات متعددة واستخدم مزودين مختلفين لوكلاء مختلفين: + ```bash + uv add "crewai[openai,anthropic,gemini]" + ``` + ```python + researcher = Agent(llm="openai/gpt-4o", ...) + writer = Agent(llm="anthropic/claude-sonnet-4-20250514", ...) + ``` + + + بغض النظر عن حالة العزل، فإن تقليل سطح اعتمادياتك يُعد ممارسة أمنية جيدة. إذا كنت تحتاج فقط مزودين يدعمهم CrewAI أصلياً، فلا يوجد سبب لإبقاء LiteLLM مثبتاً. + + + يستخدم المزودون الأصليون نفس متغيرات البيئة التي اعتدت عليها. لا حاجة لتغييرات على `OPENAI_API_KEY` أو `ANTHROPIC_API_KEY` أو `GEMINI_API_KEY` وغيرها. + + + +## موارد ذات صلة + +- [اتصالات LLM](/ar/learn/llm-connections) — الدليل الكامل لربط CrewAI مع أي LLM +- [مفاهيم LLM](/ar/concepts/llms) — فهم نماذج اللغة الكبيرة في CrewAI +- [دليل اختيار LLM](/ar/learn/llm-selection-guide) — اختيار النموذج المناسب لحالة استخدامك diff --git a/docs/ar/learn/llm-connections.mdx b/docs/ar/learn/llm-connections.mdx new file mode 100644 index 000000000..d748d115e --- /dev/null +++ b/docs/ar/learn/llm-connections.mdx @@ -0,0 +1,214 @@ +--- +title: الاتصال بأي LLM +description: دليل شامل لدمج CrewAI مع نماذج اللغة الكبيرة المختلفة (LLMs) باستخدام LiteLLM، بما في ذلك المزودون المدعومون وخيارات الإعداد. +icon: brain-circuit +mode: "wide" +--- + +## ربط CrewAI بنماذج اللغة الكبيرة + +يتصل CrewAI بنماذج اللغة الكبيرة من خلال تكاملات SDK الأصلية لأكثر المزودين شيوعاً (OpenAI وAnthropic وGoogle Gemini وAzure وAWS Bedrock)، ويستخدم LiteLLM كاحتياط مرن لجميع المزودين الآخرين. + + + افتراضياً، يستخدم CrewAI نموذج `gpt-4o-mini`. يتم تحديد ذلك بواسطة متغير البيئة `OPENAI_MODEL_NAME`، الذي يكون قيمته الافتراضية "gpt-4o-mini" إذا لم يتم تعيينه. + يمكنك بسهولة إعداد وكلائك لاستخدام نموذج أو مزود مختلف كما هو موضح في هذا الدليل. + + +## المزودون المدعومون + +يدعم LiteLLM مجموعة واسعة من المزودين، بما في ذلك على سبيل المثال لا الحصر: + +- OpenAI +- Anthropic +- Google (Vertex AI, Gemini) +- Azure OpenAI +- AWS (Bedrock, SageMaker) +- Cohere +- VoyageAI +- Hugging Face +- Ollama +- Mistral AI +- Replicate +- Together AI +- AI21 +- Cloudflare Workers AI +- DeepInfra +- Groq +- SambaNova +- Nebius AI Studio +- [NVIDIA NIMs](https://docs.api.nvidia.com/nim/reference/models-1) +- والمزيد! + +للحصول على قائمة كاملة ومحدثة بالمزودين المدعومين، يرجى الرجوع إلى [وثائق مزودي LiteLLM](https://docs.litellm.ai/docs/providers). + + + لاستخدام أي مزود غير مغطى بتكامل أصلي، أضف LiteLLM كاعتمادية لمشروعك: + ```bash + uv add 'crewai[litellm]' + ``` + يستخدم المزودون الأصليون (OpenAI، Anthropic، Google Gemini، Azure، AWS Bedrock) إضافات SDK الخاصة بهم — راجع [أمثلة إعداد المزودين](/ar/concepts/llms#provider-configuration-examples). + + +## تغيير نموذج اللغة الكبير + +لاستخدام LLM مختلف مع وكلاء CrewAI، لديك عدة خيارات: + + + + مرر اسم النموذج كسلسلة نصية عند تهيئة الوكيل: + + ```python Code + from crewai import Agent + + # Using OpenAI's GPT-4 + openai_agent = Agent( + role='OpenAI Expert', + goal='Provide insights using GPT-4', + backstory="An AI assistant powered by OpenAI's latest model.", + llm='gpt-4' + ) + + # Using Anthropic's Claude + claude_agent = Agent( + role='Anthropic Expert', + goal='Analyze data using Claude', + backstory="An AI assistant leveraging Anthropic's language model.", + llm='claude-2' + ) + ``` + + + + لمزيد من الإعداد التفصيلي، استخدم فئة LLM: + + ```python Code + from crewai import Agent, LLM + + llm = LLM( + model="gpt-4", + temperature=0.7, + base_url="https://api.openai.com/v1", + api_key="your-api-key-here" + ) + + agent = Agent( + role='Customized LLM Expert', + goal='Provide tailored responses', + backstory="An AI assistant with custom LLM settings.", + llm=llm + ) + ``` + + + + +## خيارات الإعداد + +عند إعداد LLM لوكيلك، يمكنك الوصول إلى مجموعة واسعة من المعاملات: + +| المعامل | النوع | الوصف | +|:----------|:-----:|:-------------| +| **model** | `str` | اسم النموذج المراد استخدامه (مثل "gpt-4"، "claude-2") | +| **temperature** | `float` | يتحكم في العشوائية في المخرجات (0.0 إلى 1.0) | +| **max_tokens** | `int` | الحد الأقصى لعدد الرموز المولدة | +| **top_p** | `float` | يتحكم في تنوع المخرجات (0.0 إلى 1.0) | +| **frequency_penalty** | `float` | يعاقب الرموز الجديدة بناءً على تكرارها في النص حتى الآن | +| **presence_penalty** | `float` | يعاقب الرموز الجديدة بناءً على وجودها في النص حتى الآن | +| **stop** | `str`, `List[str]` | تسلسل(ات) لإيقاف التوليد | +| **base_url** | `str` | عنوان URL الأساسي لنقطة نهاية API | +| **api_key** | `str` | مفتاح API الخاص بك للمصادقة | + +للحصول على قائمة كاملة بالمعاملات وأوصافها، راجع وثائق فئة LLM. + +## الاتصال بنماذج LLM المتوافقة مع OpenAI + +يمكنك الاتصال بنماذج LLM المتوافقة مع OpenAI باستخدام متغيرات البيئة أو عن طريق تعيين خصائص محددة في فئة LLM: + + + + + ```python Generic + import os + + os.environ["OPENAI_API_KEY"] = "your-api-key" + os.environ["OPENAI_API_BASE"] = "https://api.your-provider.com/v1" + os.environ["OPENAI_MODEL_NAME"] = "your-model-name" + ``` + + ```python Google + import os + + # Example using Gemini's OpenAI-compatible API. + os.environ["OPENAI_API_KEY"] = "your-gemini-key" # Should start with AIza... + os.environ["OPENAI_API_BASE"] = "https://generativelanguage.googleapis.com/v1beta/openai/" + os.environ["OPENAI_MODEL_NAME"] = "openai/gemini-2.0-flash" # Add your Gemini model here, under openai/ + ``` + + + + + ```python Generic + llm = LLM( + model="custom-model-name", + api_key="your-api-key", + base_url="https://api.your-provider.com/v1" + ) + agent = Agent(llm=llm, ...) + ``` + + ```python Google + # Example using Gemini's OpenAI-compatible API + llm = LLM( + model="openai/gemini-2.0-flash", + base_url="https://generativelanguage.googleapis.com/v1beta/openai/", + api_key="your-gemini-key", # Should start with AIza... + ) + agent = Agent(llm=llm, ...) + ``` + + + + +## استخدام النماذج المحلية مع Ollama + +للنماذج المحلية مثل تلك التي يوفرها Ollama: + + + + [انقر هنا لتحميل وتثبيت Ollama](https://ollama.com/download) + + + على سبيل المثال، شغّل `ollama pull llama3.2` لتحميل النموذج. + + + + ```python Code + agent = Agent( + role='Local AI Expert', + goal='Process information using a local model', + backstory="An AI assistant running on local hardware.", + llm=LLM(model="ollama/llama3.2", base_url="http://localhost:11434") + ) + ``` + + + + +## تغيير عنوان URL الأساسي لـ API + +يمكنك تغيير عنوان URL الأساسي لـ API لأي مزود LLM عن طريق تعيين معامل `base_url`: + +```python Code +llm = LLM( + model="custom-model-name", + base_url="https://api.your-provider.com/v1", + api_key="your-api-key" +) +agent = Agent(llm=llm, ...) +``` + +هذا مفيد بشكل خاص عند العمل مع واجهات برمجة تطبيقات متوافقة مع OpenAI أو عندما تحتاج إلى تحديد نقطة نهاية مختلفة للمزود الذي اخترته. + +## الخاتمة + +من خلال الاستفادة من LiteLLM، يوفر CrewAI تكاملاً سلساً مع مجموعة واسعة من نماذج اللغة الكبيرة. تتيح لك هذه المرونة اختيار النموذج الأنسب لاحتياجاتك المحددة، سواء كنت تعطي الأولوية للأداء أو كفاءة التكلفة أو النشر المحلي. تذكر الرجوع إلى [وثائق LiteLLM](https://docs.litellm.ai/docs/) للحصول على أحدث المعلومات حول النماذج المدعومة وخيارات الإعداد. diff --git a/docs/ar/learn/llm-hooks.mdx b/docs/ar/learn/llm-hooks.mdx new file mode 100644 index 000000000..445f99349 --- /dev/null +++ b/docs/ar/learn/llm-hooks.mdx @@ -0,0 +1,427 @@ +--- +title: خطافات استدعاء LLM +description: تعلم كيفية استخدام خطافات استدعاء LLM لاعتراض وتعديل والتحكم في تفاعلات نماذج اللغة في CrewAI +mode: "wide" +--- + +توفر خطافات استدعاء LLM تحكماً دقيقاً في تفاعلات نماذج اللغة أثناء تنفيذ الوكيل. تتيح لك هذه الخطافات اعتراض استدعاءات LLM وتعديل المطالبات وتحويل الاستجابات وتنفيذ بوابات الموافقة وإضافة تسجيل أو مراقبة مخصصة. + +## نظرة عامة + +تُنفذ خطافات LLM في نقطتين حرجتين: +- **قبل استدعاء LLM**: تعديل الرسائل، التحقق من المدخلات، أو حظر التنفيذ +- **بعد استدعاء LLM**: تحويل الاستجابات، تنقية المخرجات، أو تعديل سجل المحادثة + +## أنواع الخطافات + +### خطافات ما قبل استدعاء LLM + +تُنفذ قبل كل استدعاء LLM، ويمكن لهذه الخطافات: +- فحص وتعديل الرسائل المرسلة إلى LLM +- حظر تنفيذ LLM بناءً على شروط +- تنفيذ تحديد معدل أو بوابات موافقة +- إضافة سياق أو رسائل نظام +- تسجيل تفاصيل الطلب + +**التوقيع:** +```python +def before_hook(context: LLMCallHookContext) -> bool | None: + # Return False to block execution + # Return True or None to allow execution + ... +``` + +### خطافات ما بعد استدعاء LLM + +تُنفذ بعد كل استدعاء LLM، ويمكن لهذه الخطافات: +- تعديل أو تنقية استجابات LLM +- إضافة بيانات وصفية أو تنسيق +- تسجيل تفاصيل الاستجابة +- تحديث سجل المحادثة +- تنفيذ تصفية المحتوى + +**التوقيع:** +```python +def after_hook(context: LLMCallHookContext) -> str | None: + # Return modified response string + # Return None to keep original response + ... +``` + +## سياق خطاف LLM + +يوفر كائن `LLMCallHookContext` وصولاً شاملاً لحالة التنفيذ: + +```python +class LLMCallHookContext: + executor: CrewAgentExecutor # Full executor reference + messages: list # Mutable message list + agent: Agent # Current agent + task: Task # Current task + crew: Crew # Crew instance + llm: BaseLLM # LLM instance + iterations: int # Current iteration count + response: str | None # LLM response (after hooks only) +``` + +### تعديل الرسائل + +**مهم:** قم دائماً بتعديل الرسائل في مكانها: + +```python +# ✅ Correct - modify in-place +def add_context(context: LLMCallHookContext) -> None: + context.messages.append({"role": "system", "content": "Be concise"}) + +# ❌ Wrong - replaces list reference +def wrong_approach(context: LLMCallHookContext) -> None: + context.messages = [{"role": "system", "content": "Be concise"}] +``` + +## طرق التسجيل + +### 1. تسجيل الخطافات العامة + +تسجيل خطافات تنطبق على جميع استدعاءات LLM عبر جميع الأطقم: + +```python +from crewai.hooks import register_before_llm_call_hook, register_after_llm_call_hook + +def log_llm_call(context): + print(f"LLM call by {context.agent.role} at iteration {context.iterations}") + return None # Allow execution + +register_before_llm_call_hook(log_llm_call) +``` + +### 2. التسجيل باستخدام المزخرفات + +استخدم المزخرفات لصياغة أنظف: + +```python +from crewai.hooks import before_llm_call, after_llm_call + +@before_llm_call +def validate_iteration_count(context): + if context.iterations > 10: + print("⚠️ Exceeded maximum iterations") + return False # Block execution + return None + +@after_llm_call +def sanitize_response(context): + if context.response and "API_KEY" in context.response: + return context.response.replace("API_KEY", "[REDACTED]") + return None +``` + +### 3. خطافات نطاق الطاقم + +تسجيل خطافات لمثيل طاقم محدد: + +```python +@CrewBase +class MyProjCrew: + @before_llm_call_crew + def validate_inputs(self, context): + # Only applies to this crew + if context.iterations == 0: + print(f"Starting task: {context.task.description}") + return None + + @after_llm_call_crew + def log_responses(self, context): + # Crew-specific response logging + print(f"Response length: {len(context.response)}") + return None + + @crew + def crew(self) -> Crew: + return Crew( + agents=self.agents, + tasks=self.tasks, + process=Process.sequential, + verbose=True + ) +``` + +## حالات الاستخدام الشائعة + +### 1. تحديد التكرارات + +```python +@before_llm_call +def limit_iterations(context: LLMCallHookContext) -> bool | None: + max_iterations = 15 + if context.iterations > max_iterations: + print(f"⛔ Blocked: Exceeded {max_iterations} iterations") + return False # Block execution + return None +``` + +### 2. بوابة الموافقة البشرية + +```python +@before_llm_call +def require_approval(context: LLMCallHookContext) -> bool | None: + if context.iterations > 5: + response = context.request_human_input( + prompt=f"Iteration {context.iterations}: Approve LLM call?", + default_message="Press Enter to approve, or type 'no' to block:" + ) + if response.lower() == "no": + print("🚫 LLM call blocked by user") + return False + return None +``` + +### 3. إضافة سياق النظام + +```python +@before_llm_call +def add_guardrails(context: LLMCallHookContext) -> None: + # Add safety guidelines to every LLM call + context.messages.append({ + "role": "system", + "content": "Ensure responses are factual and cite sources when possible." + }) + return None +``` + +### 4. تنقية الاستجابات + +```python +@after_llm_call +def sanitize_sensitive_data(context: LLMCallHookContext) -> str | None: + if not context.response: + return None + + # Remove sensitive patterns + import re + sanitized = context.response + sanitized = re.sub(r'\b\d{3}-\d{2}-\d{4}\b', '[SSN-REDACTED]', sanitized) + sanitized = re.sub(r'\b\d{4}[- ]?\d{4}[- ]?\d{4}[- ]?\d{4}\b', '[CARD-REDACTED]', sanitized) + + return sanitized +``` + +### 5. تتبع التكاليف + +```python +import tiktoken + +@before_llm_call +def track_token_usage(context: LLMCallHookContext) -> None: + encoding = tiktoken.get_encoding("cl100k_base") + total_tokens = sum( + len(encoding.encode(msg.get("content", ""))) + for msg in context.messages + ) + print(f"📊 Input tokens: ~{total_tokens}") + return None + +@after_llm_call +def track_response_tokens(context: LLMCallHookContext) -> None: + if context.response: + encoding = tiktoken.get_encoding("cl100k_base") + tokens = len(encoding.encode(context.response)) + print(f"📊 Response tokens: ~{tokens}") + return None +``` + +### 6. تسجيل التصحيح + +```python +@before_llm_call +def debug_request(context: LLMCallHookContext) -> None: + print(f""" + 🔍 LLM Call Debug: + - Agent: {context.agent.role} + - Task: {context.task.description[:50]}... + - Iteration: {context.iterations} + - Message Count: {len(context.messages)} + - Last Message: {context.messages[-1] if context.messages else 'None'} + """) + return None + +@after_llm_call +def debug_response(context: LLMCallHookContext) -> None: + if context.response: + print(f"✅ Response Preview: {context.response[:100]}...") + return None +``` + +## إدارة الخطافات + +### إلغاء تسجيل الخطافات + +```python +from crewai.hooks import ( + unregister_before_llm_call_hook, + unregister_after_llm_call_hook +) + +# Unregister specific hook +def my_hook(context): + ... + +register_before_llm_call_hook(my_hook) +# Later... +unregister_before_llm_call_hook(my_hook) # Returns True if found +``` + +### مسح الخطافات + +```python +from crewai.hooks import ( + clear_before_llm_call_hooks, + clear_after_llm_call_hooks, + clear_all_llm_call_hooks +) + +# Clear specific hook type +count = clear_before_llm_call_hooks() +print(f"Cleared {count} before hooks") + +# Clear all LLM hooks +before_count, after_count = clear_all_llm_call_hooks() +print(f"Cleared {before_count} before and {after_count} after hooks") +``` + +### عرض الخطافات المسجلة + +```python +from crewai.hooks import ( + get_before_llm_call_hooks, + get_after_llm_call_hooks +) + +# Get current hooks +before_hooks = get_before_llm_call_hooks() +after_hooks = get_after_llm_call_hooks() + +print(f"Registered: {len(before_hooks)} before, {len(after_hooks)} after") +``` + +## أنماط متقدمة + +### تنفيذ خطاف مشروط + +```python +@before_llm_call +def conditional_blocking(context: LLMCallHookContext) -> bool | None: + # Only block for specific agents + if context.agent.role == "researcher" and context.iterations > 10: + return False + + # Only block for specific tasks + if "sensitive" in context.task.description.lower() and context.iterations > 5: + return False + + return None +``` + +### تعديلات واعية بالسياق + +```python +@before_llm_call +def adaptive_prompting(context: LLMCallHookContext) -> None: + # Add different context based on iteration + if context.iterations == 0: + context.messages.append({ + "role": "system", + "content": "Start with a high-level overview." + }) + elif context.iterations > 3: + context.messages.append({ + "role": "system", + "content": "Focus on specific details and provide examples." + }) + return None +``` + +### ربط الخطافات + +```python +# Multiple hooks execute in registration order + +@before_llm_call +def first_hook(context): + print("1. First hook executed") + return None + +@before_llm_call +def second_hook(context): + print("2. Second hook executed") + return None + +@before_llm_call +def blocking_hook(context): + if context.iterations > 10: + print("3. Blocking hook - execution stopped") + return False # Subsequent hooks won't execute + print("3. Blocking hook - execution allowed") + return None +``` + +## أفضل الممارسات + +1. **اجعل الخطافات مركزة**: يجب أن يكون لكل خطاف مسؤولية واحدة +2. **تجنب الحسابات الثقيلة**: تُنفذ الخطافات في كل استدعاء LLM +3. **تعامل مع الأخطاء بأناقة**: استخدم try-except لمنع فشل الخطافات من كسر التنفيذ +4. **استخدم تلميحات الأنواع**: استفد من `LLMCallHookContext` لدعم أفضل في بيئة التطوير +5. **وثّق سلوك الخطاف**: خاصة لشروط الحظر +6. **اختبر الخطافات بشكل مستقل**: اختبر الخطافات وحدوياً قبل الاستخدام في الإنتاج +7. **امسح الخطافات في الاختبارات**: استخدم `clear_all_llm_call_hooks()` بين تشغيلات الاختبار +8. **عدّل في المكان**: قم دائماً بتعديل `context.messages` في مكانها، ولا تستبدلها + +## معالجة الأخطاء + +```python +@before_llm_call +def safe_hook(context: LLMCallHookContext) -> bool | None: + try: + # Your hook logic + if some_condition: + return False + except Exception as e: + print(f"⚠️ Hook error: {e}") + # Decide: allow or block on error + return None # Allow execution despite error +``` + +## أمان الأنواع + +```python +from crewai.hooks import LLMCallHookContext, BeforeLLMCallHookType, AfterLLMCallHookType + +# Explicit type annotations +def my_before_hook(context: LLMCallHookContext) -> bool | None: + return None + +def my_after_hook(context: LLMCallHookContext) -> str | None: + return None + +# Type-safe registration +register_before_llm_call_hook(my_before_hook) +register_after_llm_call_hook(my_after_hook) +``` + +## استكشاف الأخطاء وإصلاحها + +### الخطاف لا يُنفذ +- تحقق من أن الخطاف مسجل قبل تنفيذ الطاقم +- تحقق مما إذا كان خطاف سابق أرجع `False` (يحظر الخطافات اللاحقة) +- تأكد من أن توقيع الخطاف يطابق النوع المتوقع + +### تعديلات الرسائل لا تستمر +- استخدم التعديلات في المكان: `context.messages.append()` +- لا تستبدل القائمة: `context.messages = []` + +### تعديلات الاستجابة لا تعمل +- أرجع السلسلة النصية المعدلة من خطافات ما بعد +- إرجاع `None` يحتفظ بالاستجابة الأصلية + +## الخاتمة + +توفر خطافات استدعاء LLM إمكانيات قوية للتحكم في تفاعلات نماذج اللغة ومراقبتها في CrewAI. استخدمها لتنفيذ حواجز الأمان وبوابات الموافقة والتسجيل وتتبع التكاليف وتنقية الاستجابات. مع معالجة الأخطاء المناسبة وأمان الأنواع، تُمكّن الخطافات أنظمة وكلاء قوية وجاهزة للإنتاج. diff --git a/docs/ar/learn/llm-selection-guide.mdx b/docs/ar/learn/llm-selection-guide.mdx new file mode 100644 index 000000000..12da16c46 --- /dev/null +++ b/docs/ar/learn/llm-selection-guide.mdx @@ -0,0 +1,823 @@ +--- +title: "دليل اختيار LLM الاستراتيجي" +description: "إطار عمل استراتيجي لاختيار نموذج اللغة الكبير المناسب لوكلاء الذكاء الاصطناعي في CrewAI وكتابة تعريفات فعالة للمهام والوكلاء" +icon: "brain-circuit" +mode: "wide" +--- + +## نهج CrewAI في اختيار LLM + +بدلاً من توصيات نماذج محددة، ندعو إلى **إطار تفكير** يساعدك على اتخاذ قرارات مستنيرة بناءً على حالة استخدامك المحددة وقيودك ومتطلباتك. يتطور مشهد LLM بسرعة، مع ظهور نماذج جديدة بانتظام وتحديث النماذج الحالية بشكل متكرر. الأهم هو تطوير نهج منظم للتقييم يبقى ذا صلة بغض النظر عن النماذج المتاحة تحديداً. + + + يركز هذا الدليل على التفكير الاستراتيجي بدلاً من توصيات نماذج محددة، + حيث يتطور مشهد LLM بسرعة. + + +## إطار القرار السريع + + + + ابدأ بفهم عميق لما تتطلبه مهامك فعلاً. ضع في الاعتبار التعقيد المعرفي + المطلوب وعمق الاستدلال اللازم وتنسيق المخرجات المتوقعة وحجم السياق الذي + سيحتاج النموذج لمعالجته. سيوجه هذا التحليل الأساسي كل قرار لاحق. + + + بمجرد فهم متطلباتك، اربطها بنقاط قوة النماذج. تتفوق عائلات النماذج + المختلفة في أنواع مختلفة من العمل؛ بعضها محسّن للاستدلال والتحليل وبعضها + للإبداع وتوليد المحتوى وبعضها للسرعة والكفاءة. + + + ضع في حسبانك قيودك التشغيلية الواقعية بما في ذلك قيود الميزانية ومتطلبات + زمن الاستجابة واحتياجات خصوصية البيانات وقدرات البنية التحتية. قد لا يكون + النموذج الأفضل نظرياً هو الخيار الأفضل عملياً لوضعك. + + + ابدأ بنماذج موثوقة ومفهومة جيداً وحسّن بناءً على الأداء الفعلي في حالة + استخدامك المحددة. غالباً ما تختلف النتائج الواقعية عن المعايير النظرية، لذا + فإن الاختبار التجريبي ضروري. + + + +## Core Selection Framework + +### a. Task-First Thinking + +The most critical step in LLM selection is understanding what your task actually demands. Too often, teams select models based on general reputation or benchmark scores without carefully analyzing their specific requirements. This approach leads to either over-engineering simple tasks with expensive, complex models, or under-powering sophisticated work with models that lack the necessary capabilities. + + + + - **Simple Tasks** represent the majority of everyday AI work and include basic instruction following, straightforward data processing, and simple formatting operations. These tasks typically have clear inputs and outputs with minimal ambiguity. The cognitive load is low, and the model primarily needs to follow explicit instructions rather than engage in complex reasoning. + + - **Complex Tasks** require multi-step reasoning, strategic thinking, and the ability to handle ambiguous or incomplete information. These might involve analyzing multiple data sources, developing comprehensive strategies, or solving problems that require breaking down into smaller components. The model needs to maintain context across multiple reasoning steps and often must make inferences that aren't explicitly stated. + + - **Creative Tasks** demand a different type of cognitive capability focused on generating novel, engaging, and contextually appropriate content. This includes storytelling, marketing copy creation, and creative problem-solving. The model needs to understand nuance, tone, and audience while producing content that feels authentic and engaging rather than formulaic. + + + + + - **Structured Data** tasks require precision and consistency in format adherence. When working with JSON, XML, or database formats, the model must reliably produce syntactically correct output that can be programmatically processed. These tasks often have strict validation requirements and little tolerance for format errors, making reliability more important than creativity. + + - **Creative Content** outputs demand a balance of technical competence and creative flair. The model needs to understand audience, tone, and brand voice while producing content that engages readers and achieves specific communication goals. Quality here is often subjective and requires models that can adapt their writing style to different contexts and purposes. + + - **Technical Content** sits between structured data and creative content, requiring both precision and clarity. Documentation, code generation, and technical analysis need to be accurate and comprehensive while remaining accessible to the intended audience. The model must understand complex technical concepts and communicate them effectively. + + + + + - **Short Context** scenarios involve focused, immediate tasks where the model needs to process limited information quickly. These are often transactional interactions where speed and efficiency matter more than deep understanding. The model doesn't need to maintain extensive conversation history or process large documents. + + - **Long Context** requirements emerge when working with substantial documents, extended conversations, or complex multi-part tasks. The model needs to maintain coherence across thousands of tokens while referencing earlier information accurately. This capability becomes crucial for document analysis, comprehensive research, and sophisticated dialogue systems. + + - **Very Long Context** scenarios push the boundaries of what's currently possible, involving massive document processing, extensive research synthesis, or complex multi-session interactions. These use cases require models specifically designed for extended context handling and often involve trade-offs between context length and processing speed. + + + + +### b. Model Capability Mapping + +Understanding model capabilities requires looking beyond marketing claims and benchmark scores to understand the fundamental strengths and limitations of different model architectures and training approaches. + + + + Reasoning models represent a specialized category designed specifically for complex, multi-step thinking tasks. These models excel when problems require careful analysis, strategic planning, or systematic problem decomposition. They typically employ techniques like chain-of-thought reasoning or tree-of-thought processing to work through complex problems step by step. + + The strength of reasoning models lies in their ability to maintain logical consistency across extended reasoning chains and to break down complex problems into manageable components. They're particularly valuable for strategic planning, complex analysis, and situations where the quality of reasoning matters more than speed of response. + + However, reasoning models often come with trade-offs in terms of speed and cost. They may also be less suitable for creative tasks or simple operations where their sophisticated reasoning capabilities aren't needed. Consider these models when your tasks involve genuine complexity that benefits from systematic, step-by-step analysis. + + + + + General purpose models offer the most balanced approach to LLM selection, providing solid performance across a wide range of tasks without extreme specialization in any particular area. These models are trained on diverse datasets and optimized for versatility rather than peak performance in specific domains. + + The primary advantage of general purpose models is their reliability and predictability across different types of work. They handle most standard business tasks competently, from research and analysis to content creation and data processing. This makes them excellent choices for teams that need consistent performance across varied workflows. + + While general purpose models may not achieve the peak performance of specialized alternatives in specific domains, they offer operational simplicity and reduced complexity in model management. They're often the best starting point for new projects, allowing teams to understand their specific needs before potentially optimizing with more specialized models. + + + + + Fast and efficient models prioritize speed, cost-effectiveness, and resource efficiency over sophisticated reasoning capabilities. These models are optimized for high-throughput scenarios where quick responses and low operational costs are more important than nuanced understanding or complex reasoning. + + These models excel in scenarios involving routine operations, simple data processing, function calling, and high-volume tasks where the cognitive requirements are relatively straightforward. They're particularly valuable for applications that need to process many requests quickly or operate within tight budget constraints. + + The key consideration with efficient models is ensuring that their capabilities align with your task requirements. While they can handle many routine operations effectively, they may struggle with tasks requiring nuanced understanding, complex reasoning, or sophisticated content generation. They're best used for well-defined, routine operations where speed and cost matter more than sophistication. + + + + + Creative models are specifically optimized for content generation, writing quality, and creative thinking tasks. These models typically excel at understanding nuance, tone, and style while producing engaging, contextually appropriate content that feels natural and authentic. + + The strength of creative models lies in their ability to adapt writing style to different audiences, maintain consistent voice and tone, and generate content that engages readers effectively. They often perform better on tasks involving storytelling, marketing copy, brand communications, and other content where creativity and engagement are primary goals. + + When selecting creative models, consider not just their ability to generate text, but their understanding of audience, context, and purpose. The best creative models can adapt their output to match specific brand voices, target different audience segments, and maintain consistency across extended content pieces. + + + + + Open source models offer unique advantages in terms of cost control, customization potential, data privacy, and deployment flexibility. These models can be run locally or on private infrastructure, providing complete control over data handling and model behavior. + + The primary benefits of open source models include elimination of per-token costs, ability to fine-tune for specific use cases, complete data privacy, and independence from external API providers. They're particularly valuable for organizations with strict data privacy requirements, budget constraints, or specific customization needs. + + However, open source models require more technical expertise to deploy and maintain effectively. Teams need to consider infrastructure costs, model management complexity, and the ongoing effort required to keep models updated and optimized. The total cost of ownership may be higher than cloud-based alternatives when factoring in technical overhead. + + + + +## Strategic Configuration Patterns + +### a. Multi-Model Approach + + + Use different models for different purposes within the same crew to optimize + both performance and cost. + + +The most sophisticated CrewAI implementations often employ multiple models strategically, assigning different models to different agents based on their specific roles and requirements. This approach allows teams to optimize for both performance and cost by using the most appropriate model for each type of work. + +Planning agents benefit from reasoning models that can handle complex strategic thinking and multi-step analysis. These agents often serve as the "brain" of the operation, developing strategies and coordinating other agents' work. Content agents, on the other hand, perform best with creative models that excel at writing quality and audience engagement. Processing agents handling routine operations can use efficient models that prioritize speed and cost-effectiveness. + +**Example: Research and Analysis Crew** + +```python +from crewai import Agent, Task, Crew, LLM + +# High-capability reasoning model for strategic planning +manager_llm = LLM(model="gemini-2.5-flash-preview-05-20", temperature=0.1) + +# Creative model for content generation +content_llm = LLM(model="claude-3-5-sonnet-20241022", temperature=0.7) + +# Efficient model for data processing +processing_llm = LLM(model="gpt-4o-mini", temperature=0) + +research_manager = Agent( + role="Research Strategy Manager", + goal="Develop comprehensive research strategies and coordinate team efforts", + backstory="Expert research strategist with deep analytical capabilities", + llm=manager_llm, # High-capability model for complex reasoning + verbose=True +) + +content_writer = Agent( + role="Research Content Writer", + goal="Transform research findings into compelling, well-structured reports", + backstory="Skilled writer who excels at making complex topics accessible", + llm=content_llm, # Creative model for engaging content + verbose=True +) + +data_processor = Agent( + role="Data Analysis Specialist", + goal="Extract and organize key data points from research sources", + backstory="Detail-oriented analyst focused on accuracy and efficiency", + llm=processing_llm, # Fast, cost-effective model for routine tasks + verbose=True +) + +crew = Crew( + agents=[research_manager, content_writer, data_processor], + tasks=[...], # Your specific tasks + manager_llm=manager_llm, # Manager uses the reasoning model + verbose=True +) +``` + +The key to successful multi-model implementation is understanding how different agents interact and ensuring that model capabilities align with agent responsibilities. This requires careful planning but can result in significant improvements in both output quality and operational efficiency. + +### b. Component-Specific Selection + + + + The manager LLM plays a crucial role in hierarchical CrewAI processes, serving as the coordination point for multiple agents and tasks. This model needs to excel at delegation, task prioritization, and maintaining context across multiple concurrent operations. + + Effective manager LLMs require strong reasoning capabilities to make good delegation decisions, consistent performance to ensure predictable coordination, and excellent context management to track the state of multiple agents simultaneously. The model needs to understand the capabilities and limitations of different agents while optimizing task allocation for efficiency and quality. + + Cost considerations are particularly important for manager LLMs since they're involved in every operation. The model needs to provide sufficient capability for effective coordination while remaining cost-effective for frequent use. This often means finding models that offer good reasoning capabilities without the premium pricing of the most sophisticated options. + + + + + Function calling LLMs handle tool usage across all agents, making them critical for crews that rely heavily on external tools and APIs. These models need to excel at understanding tool capabilities, extracting parameters accurately, and handling tool responses effectively. + + The most important characteristics for function calling LLMs are precision and reliability rather than creativity or sophisticated reasoning. The model needs to consistently extract the correct parameters from natural language requests and handle tool responses appropriately. Speed is also important since tool usage often involves multiple round trips that can impact overall performance. + + Many teams find that specialized function calling models or general purpose models with strong tool support work better than creative or reasoning-focused models for this role. The key is ensuring that the model can reliably bridge the gap between natural language instructions and structured tool calls. + + + + + Individual agents can override crew-level LLM settings when their specific needs differ significantly from the general crew requirements. This capability allows for fine-tuned optimization while maintaining operational simplicity for most agents. + + Consider agent-specific overrides when an agent's role requires capabilities that differ substantially from other crew members. For example, a creative writing agent might benefit from a model optimized for content generation, while a data analysis agent might perform better with a reasoning-focused model. + + The challenge with agent-specific overrides is balancing optimization with operational complexity. Each additional model adds complexity to deployment, monitoring, and cost management. Teams should focus overrides on agents where the performance improvement justifies the additional complexity. + + + + +## Task Definition Framework + +### a. Focus on Clarity Over Complexity + +Effective task definition is often more important than model selection in determining the quality of CrewAI outputs. Well-defined tasks provide clear direction and context that enable even modest models to perform well, while poorly defined tasks can cause even sophisticated models to produce unsatisfactory results. + + + + The best task descriptions strike a balance between providing sufficient detail and maintaining clarity. They should define the specific objective clearly enough that there's no ambiguity about what success looks like, while explaining the approach or methodology in enough detail that the agent understands how to proceed. + + Effective task descriptions include relevant context and constraints that help the agent understand the broader purpose and any limitations they need to work within. They break complex work into focused steps that can be executed systematically, rather than presenting overwhelming, multi-faceted objectives that are difficult to approach systematically. + + Common mistakes include being too vague about objectives, failing to provide necessary context, setting unclear success criteria, or combining multiple unrelated tasks into a single description. The goal is to provide enough information for the agent to succeed while maintaining focus on a single, clear objective. + + + + + Expected output guidelines serve as a contract between the task definition and the agent, clearly specifying what the deliverable should look like and how it will be evaluated. These guidelines should describe both the format and structure needed, as well as the key elements that must be included for the output to be considered complete. + + The best output guidelines provide concrete examples of quality indicators and define completion criteria clearly enough that both the agent and human reviewers can assess whether the task has been completed successfully. This reduces ambiguity and helps ensure consistent results across multiple task executions. + + Avoid generic output descriptions that could apply to any task, missing format specifications that leave agents guessing about structure, unclear quality standards that make evaluation difficult, or failing to provide examples or templates that help agents understand expectations. + + + + +### b. Task Sequencing Strategy + + + + Sequential task dependencies are essential when tasks build upon previous outputs, information flows from one task to another, or quality depends on the completion of prerequisite work. This approach ensures that each task has access to the information and context it needs to succeed. + + Implementing sequential dependencies effectively requires using the context parameter to chain related tasks, building complexity gradually through task progression, and ensuring that each task produces outputs that serve as meaningful inputs for subsequent tasks. The goal is to maintain logical flow between dependent tasks while avoiding unnecessary bottlenecks. + + Sequential dependencies work best when there's a clear logical progression from one task to another and when the output of one task genuinely improves the quality or feasibility of subsequent tasks. However, they can create bottlenecks if not managed carefully, so it's important to identify which dependencies are truly necessary versus those that are merely convenient. + + + + + Parallel execution becomes valuable when tasks are independent of each other, time efficiency is important, or different expertise areas are involved that don't require coordination. This approach can significantly reduce overall execution time while allowing specialized agents to work on their areas of strength simultaneously. + + Successful parallel execution requires identifying tasks that can truly run independently, grouping related but separate work streams effectively, and planning for result integration when parallel tasks need to be combined into a final deliverable. The key is ensuring that parallel tasks don't create conflicts or redundancies that reduce overall quality. + + Consider parallel execution when you have multiple independent research streams, different types of analysis that don't depend on each other, or content creation tasks that can be developed simultaneously. However, be mindful of resource allocation and ensure that parallel execution doesn't overwhelm your available model capacity or budget. + + + + +## Optimizing Agent Configuration for LLM Performance + +### a. Role-Driven LLM Selection + + + Generic agent roles make it impossible to select the right LLM. Specific roles + enable targeted model optimization. + + +The specificity of your agent roles directly determines which LLM capabilities matter most for optimal performance. This creates a strategic opportunity to match precise model strengths with agent responsibilities. + +**Generic vs. Specific Role Impact on LLM Choice:** + +When defining roles, think about the specific domain knowledge, working style, and decision-making frameworks that would be most valuable for the tasks the agent will handle. The more specific and contextual the role definition, the better the model can embody that role effectively. + +```python +# ✅ Specific role - clear LLM requirements +specific_agent = Agent( + role="SaaS Revenue Operations Analyst", # Clear domain expertise needed + goal="Analyze recurring revenue metrics and identify growth opportunities", + backstory="Specialist in SaaS business models with deep understanding of ARR, churn, and expansion revenue", + llm=LLM(model="gpt-4o") # Reasoning model justified for complex analysis +) +``` + +**Role-to-Model Mapping Strategy:** + +- **"Research Analyst"** → Reasoning model (GPT-4o, Claude Sonnet) for complex analysis +- **"Content Editor"** → Creative model (Claude, GPT-4o) for writing quality +- **"Data Processor"** → Efficient model (GPT-4o-mini, Gemini Flash) for structured tasks +- **"API Coordinator"** → Function-calling optimized model (GPT-4o, Claude) for tool usage + +### b. Backstory as Model Context Amplifier + + + Strategic backstories multiply your chosen LLM's effectiveness by providing + domain-specific context that generic prompting cannot achieve. + + +A well-crafted backstory transforms your LLM choice from generic capability to specialized expertise. This is especially crucial for cost optimization - a well-contextualized efficient model can outperform a premium model without proper context. + +**Context-Driven Performance Example:** + +```python +# Context amplifies model effectiveness +domain_expert = Agent( + role="B2B SaaS Marketing Strategist", + goal="Develop comprehensive go-to-market strategies for enterprise software", + backstory=""" + You have 10+ years of experience scaling B2B SaaS companies from Series A to IPO. + You understand the nuances of enterprise sales cycles, the importance of product-market + fit in different verticals, and how to balance growth metrics with unit economics. + You've worked with companies like Salesforce, HubSpot, and emerging unicorns, giving + you perspective on both established and disruptive go-to-market strategies. + """, + llm=LLM(model="claude-3-5-sonnet", temperature=0.3) # Balanced creativity with domain knowledge +) + +# This context enables Claude to perform like a domain expert +# Without it, even it would produce generic marketing advice +``` + +**Backstory Elements That Enhance LLM Performance:** + +- **Domain Experience**: "10+ years in enterprise SaaS sales" +- **Specific Expertise**: "Specializes in technical due diligence for Series B+ rounds" +- **Working Style**: "Prefers data-driven decisions with clear documentation" +- **Quality Standards**: "Insists on citing sources and showing analytical work" + +### c. Holistic Agent-LLM Optimization + +The most effective agent configurations create synergy between role specificity, backstory depth, and LLM selection. Each element reinforces the others to maximize model performance. + +**Optimization Framework:** + +```python +# Example: Technical Documentation Agent +tech_writer = Agent( + role="API Documentation Specialist", # Specific role for clear LLM requirements + goal="Create comprehensive, developer-friendly API documentation", + backstory=""" + You're a technical writer with 8+ years documenting REST APIs, GraphQL endpoints, + and SDK integration guides. You've worked with developer tools companies and + understand what developers need: clear examples, comprehensive error handling, + and practical use cases. You prioritize accuracy and usability over marketing fluff. + """, + llm=LLM( + model="claude-3-5-sonnet", # Excellent for technical writing + temperature=0.1 # Low temperature for accuracy + ), + tools=[code_analyzer_tool, api_scanner_tool], + verbose=True +) +``` + +**Alignment Checklist:** + +- ✅ **Role Specificity**: Clear domain and responsibilities +- ✅ **LLM Match**: Model strengths align with role requirements +- ✅ **Backstory Depth**: Provides domain context the LLM can leverage +- ✅ **Tool Integration**: Tools support the agent's specialized function +- ✅ **Parameter Tuning**: Temperature and settings optimize for role needs + +The key is creating agents where every configuration choice reinforces your LLM selection strategy, maximizing performance while optimizing costs. + +## Practical Implementation Checklist + +Rather than repeating the strategic framework, here's a tactical checklist for implementing your LLM selection decisions in CrewAI: + + + + **What to Review:** + - Are all agents using the same LLM by default? + - Which agents handle the most complex reasoning tasks? + - Which agents primarily do data processing or formatting? + - Are any agents heavily tool-dependent? + + **Action**: Document current agent roles and identify optimization opportunities. + + + + + **Set Your Baseline:** + ```python + # Start with a reliable default for the crew + default_crew_llm = LLM(model="gpt-4o-mini") # Cost-effective baseline + + crew = Crew( + agents=[...], + tasks=[...], + memory=True + ) + ``` + + **Action**: Establish your crew's default LLM before optimizing individual agents. + + + + + **Identify and Upgrade Key Agents:** + ```python + # Manager or coordination agents + manager_agent = Agent( + role="Project Manager", + llm=LLM(model="gemini-2.5-flash-preview-05-20"), # Premium for coordination + # ... rest of config + ) + + # Creative or customer-facing agents + content_agent = Agent( + role="Content Creator", + llm=LLM(model="claude-3-5-sonnet"), # Best for writing + # ... rest of config + ) + ``` + + **Action**: Upgrade 20% of your agents that handle 80% of the complexity. + + + + + **Once you deploy your agents to production:** + - Use [CrewAI AMP platform](https://app.crewai.com) to A/B test your model selections + - Run multiple iterations with real inputs to measure consistency and performance + - Compare cost vs. performance across your optimized setup + - Share results with your team for collaborative decision-making + + **Action**: Replace guesswork with data-driven validation using the testing platform. + + + + +### When to Use Different Model Types + + + + Reasoning models become essential when tasks require genuine multi-step logical thinking, strategic planning, or high-level decision making that benefits from systematic analysis. These models excel when problems need to be broken down into components and analyzed systematically rather than handled through pattern matching or simple instruction following. + + Consider reasoning models for business strategy development, complex data analysis that requires drawing insights from multiple sources, multi-step problem solving where each step depends on previous analysis, and strategic planning tasks that require considering multiple variables and their interactions. + + However, reasoning models often come with higher costs and slower response times, so they're best reserved for tasks where their sophisticated capabilities provide genuine value rather than being used for simple operations that don't require complex reasoning. + + + + + Creative models become valuable when content generation is the primary output and the quality, style, and engagement level of that content directly impact success. These models excel when writing quality and style matter significantly, creative ideation or brainstorming is needed, or brand voice and tone are important considerations. + + Use creative models for blog post writing and article creation, marketing copy that needs to engage and persuade, creative storytelling and narrative development, and brand communications where voice and tone are crucial. These models often understand nuance and context better than general purpose alternatives. + + Creative models may be less suitable for technical or analytical tasks where precision and factual accuracy are more important than engagement and style. They're best used when the creative and communicative aspects of the output are primary success factors. + + + + + Efficient models are ideal for high-frequency, routine operations where speed and cost optimization are priorities. These models work best when tasks have clear, well-defined parameters and don't require sophisticated reasoning or creative capabilities. + + Consider efficient models for data processing and transformation tasks, simple formatting and organization operations, function calling and tool usage where precision matters more than sophistication, and high-volume operations where cost per operation is a significant factor. + + The key with efficient models is ensuring that their capabilities align with task requirements. They can handle many routine operations effectively but may struggle with tasks requiring nuanced understanding, complex reasoning, or sophisticated content generation. + + + + + Open source models become attractive when budget constraints are significant, data privacy requirements exist, customization needs are important, or local deployment is required for operational or compliance reasons. + + Consider open source models for internal company tools where data privacy is paramount, privacy-sensitive applications that can't use external APIs, cost-optimized deployments where per-token pricing is prohibitive, and situations requiring custom model modifications or fine-tuning. + + However, open source models require more technical expertise to deploy and maintain effectively. Consider the total cost of ownership including infrastructure, technical overhead, and ongoing maintenance when evaluating open source options. + + + + +## Common CrewAI Model Selection Pitfalls + + + + **The Problem**: Using the same LLM for all agents in a crew, regardless of their specific roles and responsibilities. This is often the default approach but rarely optimal. + + **Real Example**: Using GPT-4o for both a strategic planning manager and a data extraction agent. The manager needs reasoning capabilities worth the premium cost, but the data extractor could perform just as well with GPT-4o-mini at a fraction of the price. + + **CrewAI Solution**: Leverage agent-specific LLM configuration to match model capabilities with agent roles: + ```python + # Strategic agent gets premium model + manager = Agent(role="Strategy Manager", llm=LLM(model="gpt-4o")) + + # Processing agent gets efficient model + processor = Agent(role="Data Processor", llm=LLM(model="gpt-4o-mini")) + ``` + + + + + **The Problem**: Not understanding how CrewAI's LLM hierarchy works - crew LLM, manager LLM, and agent LLM settings can conflict or be poorly coordinated. + + **Real Example**: Setting a crew to use Claude, but having agents configured with GPT models, creating inconsistent behavior and unnecessary model switching overhead. + + **CrewAI Solution**: Plan your LLM hierarchy strategically: + ```python + crew = Crew( + agents=[agent1, agent2], + tasks=[task1, task2], + manager_llm=LLM(model="gpt-4o"), # For crew coordination + process=Process.hierarchical # When using manager_llm + ) + + # Agents inherit crew LLM unless specifically overridden + agent1 = Agent(llm=LLM(model="claude-3-5-sonnet")) # Override for specific needs + ``` + + + + + **The Problem**: Choosing models based on general capabilities while ignoring function calling performance for tool-heavy CrewAI workflows. + + **Real Example**: Selecting a creative-focused model for an agent that primarily needs to call APIs, search tools, or process structured data. The agent struggles with tool parameter extraction and reliable function calls. + + **CrewAI Solution**: Prioritize function calling capabilities for tool-heavy agents: + ```python + # For agents that use many tools + tool_agent = Agent( + role="API Integration Specialist", + tools=[search_tool, api_tool, data_tool], + llm=LLM(model="gpt-4o"), # Excellent function calling + # OR + llm=LLM(model="claude-3-5-sonnet") # Also strong with tools + ) + ``` + + + + + **The Problem**: Making complex model selection decisions based on theoretical performance without validating with actual CrewAI workflows and tasks. + + **Real Example**: Implementing elaborate model switching logic based on task types without testing if the performance gains justify the operational complexity. + + **CrewAI Solution**: Start simple, then optimize based on real performance data: + ```python + # Start with this + crew = Crew(agents=[...], tasks=[...], llm=LLM(model="gpt-4o-mini")) + + # Test performance, then optimize specific agents as needed + # Use Enterprise platform testing to validate improvements + ``` + + + + + **The Problem**: Not considering how model context windows interact with CrewAI's memory and context sharing between agents. + + **Real Example**: Using a short-context model for agents that need to maintain conversation history across multiple task iterations, or in crews with extensive agent-to-agent communication. + + **CrewAI Solution**: Match context capabilities to crew communication patterns. + + + + +## Testing and Iteration Strategy + + + + Begin with reliable, general-purpose models that are well-understood and + widely supported. This provides a stable foundation for understanding your + specific requirements and performance expectations before optimizing for + specialized needs. + + + Develop metrics that align with your specific use case and business + requirements rather than relying solely on general benchmarks. Focus on + measuring outcomes that directly impact your success rather than theoretical + performance indicators. + + + Make model changes based on observed performance in your specific context + rather than theoretical considerations or general recommendations. + Real-world performance often differs significantly from benchmark results or + general reputation. + + + Evaluate the complete cost of ownership including model costs, development + time, maintenance overhead, and operational complexity. The cheapest model + per token may not be the most cost-effective choice when considering all + factors. + + + + + Focus on understanding your requirements first, then select models that best + match those needs. The best LLM choice is the one that consistently delivers + the results you need within your operational constraints. + + +### Enterprise-Grade Model Validation + +For teams serious about optimizing their LLM selection, the **CrewAI AMP platform** provides sophisticated testing capabilities that go far beyond basic CLI testing. The platform enables comprehensive model evaluation that helps you make data-driven decisions about your LLM strategy. + + + ![Enterprise Testing Interface](/images/enterprise/enterprise-testing.png) + + +**Advanced Testing Features:** + +- **Multi-Model Comparison**: Test multiple LLMs simultaneously across the same tasks and inputs. Compare performance between GPT-4o, Claude, Llama, Groq, Cerebras, and other leading models in parallel to identify the best fit for your specific use case. + +- **Statistical Rigor**: Configure multiple iterations with consistent inputs to measure reliability and performance variance. This helps identify models that not only perform well but do so consistently across runs. + +- **Real-World Validation**: Use your actual crew inputs and scenarios rather than synthetic benchmarks. The platform allows you to test with your specific industry context, company information, and real use cases for more accurate evaluation. + +- **Comprehensive Analytics**: Access detailed performance metrics, execution times, and cost analysis across all tested models. This enables data-driven decision making rather than relying on general model reputation or theoretical capabilities. + +- **Team Collaboration**: Share testing results and model performance data across your team, enabling collaborative decision-making and consistent model selection strategies across projects. + +Go to [app.crewai.com](https://app.crewai.com) to get started! + + + The Enterprise platform transforms model selection from guesswork into a + data-driven process, enabling you to validate the principles in this guide + with your actual use cases and requirements. + + +## Key Principles Summary + + + + Choose models based on what the task actually requires, not theoretical capabilities or general reputation. + + +{" "} + + Align model strengths with agent roles and responsibilities for optimal + performance. + + +{" "} + + Maintain coherent model selection strategy across related components and + workflows. + + +{" "} + + Validate choices through real-world usage rather than benchmarks alone. + + +{" "} + + Start simple and optimize based on actual performance and needs. + + + + Balance performance requirements with cost and complexity constraints. + + + + + Remember: The best LLM choice is the one that consistently delivers the + results you need within your operational constraints. Focus on understanding + your requirements first, then select models that best match those needs. + + +## Current Model Landscape (June 2025) + + + **Snapshot in Time**: The following model rankings represent current + leaderboard standings as of June 2025, compiled from [LMSys + Arena](https://arena.lmsys.org/), [Artificial + Analysis](https://artificialanalysis.ai/), and other leading benchmarks. LLM + performance, availability, and pricing change rapidly. Always conduct your own + evaluations with your specific use cases and data. + + +### Leading Models by Category + +The tables below show a representative sample of current top-performing models across different categories, with guidance on their suitability for CrewAI agents: + + + These tables/metrics showcase selected leading models in each category and are + not exhaustive. Many excellent models exist beyond those listed here. The goal + is to illustrate the types of capabilities to look for rather than provide a + complete catalog. + + + + + **Best for Manager LLMs and Complex Analysis** + + | Model | Intelligence Score | Cost ($/M tokens) | Speed | Best Use in CrewAI | + |:------|:------------------|:------------------|:------|:------------------| + | **o3** | 70 | $17.50 | Fast | Manager LLM for complex multi-agent coordination | + | **Gemini 2.5 Pro** | 69 | $3.44 | Fast | Strategic planning agents, research coordination | + | **DeepSeek R1** | 68 | $0.96 | Moderate | Cost-effective reasoning for budget-conscious crews | + | **Claude 4 Sonnet** | 53 | $6.00 | Fast | Analysis agents requiring nuanced understanding | + | **Qwen3 235B (Reasoning)** | 62 | $2.63 | Moderate | Open-source alternative for reasoning tasks | + + These models excel at multi-step reasoning and are ideal for agents that need to develop strategies, coordinate other agents, or analyze complex information. + + + + + **Best for Development and Tool-Heavy Workflows** + + | Model | Coding Performance | Tool Use Score | Cost ($/M tokens) | Best Use in CrewAI | + |:------|:------------------|:---------------|:------------------|:------------------| + | **Claude 4 Sonnet** | Excellent | 72.7% | $6.00 | Primary coding agent, technical documentation | + | **Claude 4 Opus** | Excellent | 72.5% | $30.00 | Complex software architecture, code review | + | **DeepSeek V3** | Very Good | High | $0.48 | Cost-effective coding for routine development | + | **Qwen2.5 Coder 32B** | Very Good | Medium | $0.15 | Budget-friendly coding agent | + | **Llama 3.1 405B** | Good | 81.1% | $3.50 | Function calling LLM for tool-heavy workflows | + + These models are optimized for code generation, debugging, and technical problem-solving, making them ideal for development-focused crews. + + + + + **Best for High-Throughput and Real-Time Applications** + + | Model | Speed (tokens/s) | Latency (TTFT) | Cost ($/M tokens) | Best Use in CrewAI | + |:------|:-----------------|:---------------|:------------------|:------------------| + | **Llama 4 Scout** | 2,600 | 0.33s | $0.27 | High-volume processing agents | + | **Gemini 2.5 Flash** | 376 | 0.30s | $0.26 | Real-time response agents | + | **DeepSeek R1 Distill** | 383 | Variable | $0.04 | Cost-optimized high-speed processing | + | **Llama 3.3 70B** | 2,500 | 0.52s | $0.60 | Balanced speed and capability | + | **Nova Micro** | High | 0.30s | $0.04 | Simple, fast task execution | + + These models prioritize speed and efficiency, perfect for agents handling routine operations or requiring quick responses. **Pro tip**: Pairing these models with fast inference providers like Groq can achieve even better performance, especially for open-source models like Llama. + + + + + **Best All-Around Models for General Crews** + + | Model | Overall Score | Versatility | Cost ($/M tokens) | Best Use in CrewAI | + |:------|:--------------|:------------|:------------------|:------------------| + | **GPT-4.1** | 53 | Excellent | $3.50 | General-purpose crew LLM | + | **Claude 3.7 Sonnet** | 48 | Very Good | $6.00 | Balanced reasoning and creativity | + | **Gemini 2.0 Flash** | 48 | Good | $0.17 | Cost-effective general use | + | **Llama 4 Maverick** | 51 | Good | $0.37 | Open-source general purpose | + | **Qwen3 32B** | 44 | Good | $1.23 | Budget-friendly versatility | + + These models offer good performance across multiple dimensions, suitable for crews with diverse task requirements. + + + + +### Selection Framework for Current Models + + + + **When performance is the priority**: Use top-tier models like **o3**, **Gemini 2.5 Pro**, or **Claude 4 Sonnet** for manager LLMs and critical agents. These models excel at complex reasoning and coordination but come with higher costs. + + **Strategy**: Implement a multi-model approach where premium models handle strategic thinking while efficient models handle routine operations. + + + + + **When budget is a primary constraint**: Focus on models like **DeepSeek R1**, **Llama 4 Scout**, or **Gemini 2.0 Flash**. These provide strong performance at significantly lower costs. + + **Strategy**: Use cost-effective models for most agents, reserving premium models only for the most critical decision-making roles. + + + + + **For specific domain expertise**: Choose models optimized for your primary use case. **Claude 4** series for coding, **Gemini 2.5 Pro** for research, **Llama 405B** for function calling. + + **Strategy**: Select models based on your crew's primary function, ensuring the core capability aligns with model strengths. + + + + + **For data-sensitive operations**: Consider open-source models like **Llama 4** series, **DeepSeek V3**, or **Qwen3** that can be deployed locally while maintaining competitive performance. + + **Strategy**: Deploy open-source models on private infrastructure, accepting potential performance trade-offs for data control. + + + + +### Key Considerations for Model Selection + +- **Performance Trends**: The current landscape shows strong competition between reasoning-focused models (o3, Gemini 2.5 Pro) and balanced models (Claude 4, GPT-4.1). Specialized models like DeepSeek R1 offer excellent cost-performance ratios. + +- **Speed vs. Intelligence Trade-offs**: Models like Llama 4 Scout prioritize speed (2,600 tokens/s) while maintaining reasonable intelligence, whereas models like o3 maximize reasoning capability at the cost of speed and price. + +- **Open Source Viability**: The gap between open-source and proprietary models continues to narrow, with models like Llama 4 Maverick and DeepSeek V3 offering competitive performance at attractive price points. Fast inference providers particularly shine with open-source models, often delivering better speed-to-cost ratios than proprietary alternatives. + + + **Testing is Essential**: Leaderboard rankings provide general guidance, but + your specific use case, prompting style, and evaluation criteria may produce + different results. Always test candidate models with your actual tasks and + data before making final decisions. + + +### Practical Implementation Strategy + + + + Begin with well-established models like **GPT-4.1**, **Claude 3.7 Sonnet**, or **Gemini 2.0 Flash** that offer good performance across multiple dimensions and have extensive real-world validation. + + +{" "} + + Determine if your crew has specific requirements (coding, reasoning, speed) + that would benefit from specialized models like **Claude 4 Sonnet** for + development or **o3** for complex analysis. For speed-critical applications, + consider fast inference providers like **Groq** alongside model selection. + + +{" "} + + Use different models for different agents based on their roles. + High-capability models for managers and complex tasks, efficient models for + routine operations. + + + + Track performance metrics relevant to your use case and be prepared to adjust model selections as new models are released or pricing changes. + + diff --git a/docs/ar/learn/multimodal-agents.mdx b/docs/ar/learn/multimodal-agents.mdx new file mode 100644 index 000000000..9c80f969c --- /dev/null +++ b/docs/ar/learn/multimodal-agents.mdx @@ -0,0 +1,141 @@ +--- +title: استخدام الوكلاء متعددي الوسائط +description: تعلم كيفية تفعيل واستخدام القدرات متعددة الوسائط في وكلائك لمعالجة الصور والمحتوى غير النصي ضمن إطار عمل CrewAI. +icon: video +mode: "wide" +--- + +## استخدام الوكلاء متعددي الوسائط + +يدعم CrewAI الوكلاء متعددي الوسائط القادرين على معالجة المحتوى النصي وغير النصي مثل الصور. سيوضح لك هذا الدليل كيفية تفعيل واستخدام القدرات متعددة الوسائط في وكلائك. + +### تفعيل القدرات متعددة الوسائط + +لإنشاء وكيل متعدد الوسائط، ما عليك سوى تعيين معامل `multimodal` إلى `True` عند تهيئة وكيلك: + +```python +from crewai import Agent + +agent = Agent( + role="Image Analyst", + goal="Analyze and extract insights from images", + backstory="An expert in visual content interpretation with years of experience in image analysis", + multimodal=True # This enables multimodal capabilities +) +``` + +عند تعيين `multimodal=True`، يتم إعداد الوكيل تلقائياً بالأدوات اللازمة للتعامل مع المحتوى غير النصي، بما في ذلك `AddImageTool`. + +### العمل مع الصور + +يأتي الوكيل متعدد الوسائط مُعداً مسبقاً بأداة `AddImageTool`، التي تتيح له معالجة الصور. لا تحتاج إلى إضافة هذه الأداة يدوياً — فهي مضمنة تلقائياً عند تفعيل القدرات متعددة الوسائط. + +إليك مثالاً كاملاً يوضح كيفية استخدام وكيل متعدد الوسائط لتحليل صورة: + +```python +from crewai import Agent, Task, Crew + +# Create a multimodal agent +image_analyst = Agent( + role="Product Analyst", + goal="Analyze product images and provide detailed descriptions", + backstory="Expert in visual product analysis with deep knowledge of design and features", + multimodal=True +) + +# Create a task for image analysis +task = Task( + description="Analyze the product image at https://example.com/product.jpg and provide a detailed description", + expected_output="A detailed description of the product image", + agent=image_analyst +) + +# Create and run the crew +crew = Crew( + agents=[image_analyst], + tasks=[task] +) + +result = crew.kickoff() +``` + +### الاستخدام المتقدم مع السياق + +يمكنك تقديم سياق إضافي أو أسئلة محددة حول الصورة عند إنشاء مهام للوكلاء متعددي الوسائط. يمكن أن يتضمن وصف المهمة جوانب محددة تريد أن يركز عليها الوكيل: + +```python +from crewai import Agent, Task, Crew + +# Create a multimodal agent for detailed analysis +expert_analyst = Agent( + role="Visual Quality Inspector", + goal="Perform detailed quality analysis of product images", + backstory="Senior quality control expert with expertise in visual inspection", + multimodal=True # AddImageTool is automatically included +) + +# Create a task with specific analysis requirements +inspection_task = Task( + description=""" + Analyze the product image at https://example.com/product.jpg with focus on: + 1. Quality of materials + 2. Manufacturing defects + 3. Compliance with standards + Provide a detailed report highlighting any issues found. + """, + expected_output="A detailed report highlighting any issues found", + agent=expert_analyst +) + +# Create and run the crew +crew = Crew( + agents=[expert_analyst], + tasks=[inspection_task] +) + +result = crew.kickoff() +``` + +### تفاصيل الأداة + +عند العمل مع الوكلاء متعددي الوسائط، يتم إعداد `AddImageTool` تلقائياً بالمخطط التالي: + +```python +class AddImageToolSchema: + image_url: str # Required: The URL or path of the image to process + action: Optional[str] = None # Optional: Additional context or specific questions about the image +``` + +سيتعامل الوكيل متعدد الوسائط تلقائياً مع معالجة الصور من خلال أدواته المدمجة، مما يتيح له: +- الوصول إلى الصور عبر عناوين URL أو مسارات الملفات المحلية +- معالجة محتوى الصورة مع سياق اختياري أو أسئلة محددة +- تقديم تحليلات ورؤى بناءً على المعلومات البصرية ومتطلبات المهمة + +### أفضل الممارسات + +عند العمل مع الوكلاء متعددي الوسائط، ضع هذه الممارسات في الاعتبار: + +1. **الوصول إلى الصور** + - تأكد من أن صورك قابلة للوصول عبر عناوين URL التي يمكن للوكيل الوصول إليها + - للصور المحلية، فكر في استضافتها مؤقتاً أو استخدام مسارات ملفات مطلقة + - تحقق من أن عناوين URL للصور صالحة وقابلة للوصول قبل تشغيل المهام + +2. **وصف المهمة** + - كن محدداً حول الجوانب التي تريد من الوكيل تحليلها في الصورة + - قم بتضمين أسئلة أو متطلبات واضحة في وصف المهمة + - فكر في استخدام معامل `action` الاختياري للتحليل المركز + +3. **إدارة الموارد** + - قد تتطلب معالجة الصور موارد حسابية أكثر من المهام النصية فقط + - قد تتطلب بعض نماذج اللغة ترميز base64 لبيانات الصورة + - فكر في المعالجة الدفعية لصور متعددة لتحسين الأداء + +4. **إعداد البيئة** + - تحقق من أن بيئتك تحتوي على الاعتماديات اللازمة لمعالجة الصور + - تأكد من أن نموذج اللغة الخاص بك يدعم القدرات متعددة الوسائط + - اختبر بصور صغيرة أولاً للتحقق من إعدادك + +5. **معالجة الأخطاء** + - نفّذ معالجة أخطاء مناسبة لحالات فشل تحميل الصور + - ضع استراتيجيات احتياطية لحالات فشل معالجة الصور + - راقب وسجل عمليات معالجة الصور لأغراض التصحيح diff --git a/docs/ar/learn/overview.mdx b/docs/ar/learn/overview.mdx new file mode 100644 index 000000000..b09a944fd --- /dev/null +++ b/docs/ar/learn/overview.mdx @@ -0,0 +1,159 @@ +--- +title: "نظرة عامة" +description: "تعلم كيفية بناء وتخصيص وتحسين تطبيقات CrewAI الخاصة بك مع أدلة وبرامج تعليمية شاملة" +icon: "face-smile" +mode: "wide" +--- + +## تعلم CrewAI + +يوفر هذا القسم أدلة وبرامج تعليمية شاملة لمساعدتك في إتقان CrewAI، من المفاهيم الأساسية إلى التقنيات المتقدمة. سواء كنت قد بدأت للتو أو تبحث عن تحسين تطبيقاتك الحالية، ستوجهك هذه الموارد عبر كل جانب من جوانب بناء سير عمل وكلاء الذكاء الاصطناعي القوية. + +## أدلة البدء + +### المفاهيم الأساسية + + + تعلم كيفية تنفيذ المهام بترتيب تسلسلي لسير عمل منظم. + + + + تنفيذ تنفيذ المهام الهرمي مع وكلاء مديرين يشرفون على سير العمل. + + + + إنشاء سير عمل ديناميكي مع تنفيذ مهام شرطي بناءً على النتائج. + + + + تنفيذ الأطقم بشكل غير متزامن لأداء وتزامن محسّن. + + + +### تطوير الوكلاء + + + تعلم كيفية تخصيص سلوك الوكلاء وأدوارهم وقدراتهم. + + + + بناء وكلاء يمكنهم كتابة وتنفيذ وتصحيح الكود تلقائياً. + + + + إنشاء وكلاء يمكنهم معالجة النصوص والصور وأنواع الوسائط الأخرى. + + + + تنفيذ وكلاء مديرين مخصصين لسير العمل الهرمي المعقد. + + + +## الميزات المتقدمة + +### التحكم في سير العمل + + + دمج الإشراف البشري والتدخل في سير عمل الوكلاء. + + + + السماح بالإدخال البشري أثناء تنفيذ المهام لاتخاذ قرارات ديناميكية. + + + + إعادة تشغيل واستئناف المهام من عمليات تنفيذ الطاقم السابقة. + + + + تنفيذ الأطقم عدة مرات بمدخلات مختلفة بكفاءة. + + + +### التخصيص والتكامل + + + دمج نماذج لغة ومزودين مخصصين مع CrewAI. + + + + إعداد وإدارة الاتصالات بمزودي LLM المختلفين. + + + + بناء أدوات مخصصة لتوسيع قدرات الوكلاء. + + + + استخدام تعليقات Python التوضيحية لكود أنظف وأسهل في الصيانة. + + + +## التطبيقات المتخصصة + +### المحتوى والوسائط + + + توليد الصور باستخدام تكامل DALL-E مع وكلائك. + + + + دمج الوكلاء والنماذج الموجودة في سير عمل CrewAI. + + + +### إدارة الأدوات + + + إعداد الأدوات لإرجاع مخرجاتها مباشرة كنتائج للمهام. + + + +## توصيات مسار التعلم + +### للمبتدئين +1. ابدأ بـ **العملية التسلسلية** لفهم تنفيذ سير العمل الأساسي +2. تعلم **تخصيص الوكلاء** لإنشاء إعدادات وكلاء فعالة +3. استكشف **إنشاء أدوات مخصصة** لتوسيع الوظائف +4. جرب **الإنسان في الحلقة** لسير العمل التفاعلي + +### للمستخدمين المتوسطين +1. أتقن **العملية الهرمية** لأنظمة الوكلاء المتعددة المعقدة +2. نفّذ **المهام الشرطية** لسير العمل الديناميكي +3. استخدم **التشغيل غير المتزامن** لتحسين الأداء +4. ادمج **LLM مخصص** للنماذج المتخصصة + +### للمستخدمين المتقدمين +1. ابنِ **وكلاء متعددي الوسائط** لمعالجة الوسائط المعقدة +2. أنشئ **وكلاء مديرين مخصصين** للتنسيق المتطور +3. نفّذ **أحضر وكيلك الخاص** للأنظمة الهجينة +4. استخدم **إعادة تشغيل المهام** لاسترداد الأخطاء بشكل متين + +## أفضل الممارسات + +### التطوير +- **ابدأ بالبساطة**: ابدأ بسير العمل التسلسلي الأساسي قبل إضافة التعقيد +- **اختبر تدريجياً**: اختبر كل مكون قبل دمجه في أنظمة أكبر +- **استخدم التعليقات التوضيحية**: استفد من تعليقات Python التوضيحية لكود أنظف وأسهل في الصيانة +- **أدوات مخصصة**: ابنِ أدوات قابلة لإعادة الاستخدام يمكن مشاركتها عبر وكلاء مختلفين + +### الإنتاج +- **معالجة الأخطاء**: نفّذ معالجة أخطاء وآليات استرداد قوية +- **الأداء**: استخدم التنفيذ غير المتزامن وحسّن استدعاءات LLM لأداء أفضل +- **المراقبة**: ادمج أدوات المراقبة لتتبع أداء الوكلاء +- **الإشراف البشري**: ضمّن نقاط تفتيش بشرية للقرارات الحرجة + +### التحسين +- **إدارة الموارد**: راقب وحسّن استخدام الرموز وتكاليف API +- **تصميم سير العمل**: صمم سير عمل يقلل من استدعاءات LLM غير الضرورية +- **كفاءة الأدوات**: أنشئ أدوات فعالة توفر أقصى قيمة بأقل حمل +- **التحسين التكراري**: استخدم التغذية الراجعة والمقاييس لتحسين أداء الوكلاء باستمرار + +## الحصول على المساعدة + +- **التوثيق**: يتضمن كل دليل أمثلة وشروحات مفصلة +- **المجتمع**: انضم إلى [منتدى CrewAI](https://community.crewai.com) للمناقشات والدعم +- **الأمثلة**: تحقق من قسم الأمثلة للتطبيقات العاملة الكاملة +- **الدعم**: تواصل مع [support@crewai.com](mailto:support@crewai.com) للمساعدة التقنية + +ابدأ بالأدلة التي تتوافق مع احتياجاتك الحالية واستكشف تدريجياً المواضيع الأكثر تقدماً مع إتقانك للأساسيات. diff --git a/docs/ar/learn/replay-tasks-from-latest-crew-kickoff.mdx b/docs/ar/learn/replay-tasks-from-latest-crew-kickoff.mdx new file mode 100644 index 000000000..069e25c31 --- /dev/null +++ b/docs/ar/learn/replay-tasks-from-latest-crew-kickoff.mdx @@ -0,0 +1,79 @@ +--- +title: إعادة تشغيل المهام من آخر تنفيذ للطاقم +description: إعادة تشغيل المهام من آخر crew.kickoff(...) +icon: arrow-right +mode: "wide" +--- + +## مقدمة + +يوفر CrewAI القدرة على إعادة التشغيل من مهمة محددة من آخر تشغيل للطاقم. هذه الميزة مفيدة بشكل خاص عندما تكون قد أنهيت تشغيلاً وقد ترغب في إعادة محاولة مهام معينة أو لا تحتاج إلى إعادة جلب البيانات ووكلاؤك لديهم بالفعل السياق المحفوظ من تنفيذ التشغيل، لذا تحتاج فقط إلى إعادة تشغيل المهام التي تريدها. + + + يجب عليك تشغيل `crew.kickoff()` قبل أن تتمكن من إعادة تشغيل مهمة. + حالياً، يُدعم فقط آخر تشغيل، لذا إذا استخدمت `kickoff_for_each`، فسيسمح لك فقط بإعادة التشغيل من أحدث تشغيل للطاقم. + + +إليك مثالاً على كيفية إعادة التشغيل من مهمة: + +### إعادة التشغيل من مهمة محددة باستخدام CLI + +لاستخدام ميزة إعادة التشغيل، اتبع هذه الخطوات: + + + + + + لعرض معرفات المهام من آخر تشغيل، استخدم: + + ```shell + crewai log-tasks-outputs + ``` + + بمجرد حصولك على `task_id` لإعادة التشغيل، استخدم: + + ```shell + crewai replay -t + ``` + + + + + تأكد من أن `crewai` مثبت ومُعد بشكل صحيح في بيئة التطوير الخاصة بك. + + +### إعادة التشغيل من مهمة برمجياً + +لإعادة التشغيل من مهمة برمجياً، استخدم الخطوات التالية: + + + + حدد `task_id` ومعاملات الإدخال لعملية إعادة التشغيل. + + + نفّذ أمر إعادة التشغيل ضمن كتلة try-except للتعامل مع الأخطاء المحتملة. + + ```python Code + def replay(): + """ + Replay the crew execution from a specific task. + """ + task_id = '' + inputs = {"topic": "CrewAI Training"} # This is optional; you can pass in the inputs you want to replay; otherwise, it uses the previous kickoff's inputs. + try: + YourCrewName_Crew().crew().replay(task_id=task_id, inputs=inputs) + + except subprocess.CalledProcessError as e: + raise Exception(f"An error occurred while replaying the crew: {e}") + + except Exception as e: + raise Exception(f"An unexpected error occurred: {e}") + ``` + + + + +## الخاتمة + +مع التحسينات المذكورة أعلاه والوظائف المفصلة، أصبحت إعادة تشغيل مهام محددة في CrewAI أكثر كفاءة ومتانة. +تأكد من اتباع الأوامر والخطوات بدقة لتحقيق أقصى استفادة من هذه الميزات. diff --git a/docs/ar/learn/sequential-process.mdx b/docs/ar/learn/sequential-process.mdx new file mode 100644 index 000000000..7ef2d66bf --- /dev/null +++ b/docs/ar/learn/sequential-process.mdx @@ -0,0 +1,128 @@ +--- +title: العمليات التسلسلية +description: دليل شامل لاستخدام العمليات التسلسلية لتنفيذ المهام في مشاريع CrewAI. +icon: forward +mode: "wide" +--- + +## مقدمة + +يقدم CrewAI إطار عمل مرن لتنفيذ المهام بطريقة منظمة، يدعم كلاً من العمليات التسلسلية والهرمية. +يوضح هذا الدليل كيفية تنفيذ هذه العمليات بفعالية لضمان تنفيذ المهام بكفاءة وإكمال المشروع. + +## نظرة عامة على العملية التسلسلية + +تضمن العملية التسلسلية تنفيذ المهام واحدة تلو الأخرى، باتباع تقدم خطي. +هذا النهج مثالي للمشاريع التي تتطلب إكمال المهام بترتيب محدد. + +### الميزات الرئيسية + +- **تدفق مهام خطي**: يضمن تقدماً منظماً من خلال التعامل مع المهام بتسلسل محدد مسبقاً. +- **البساطة**: الأنسب للمشاريع ذات المهام الواضحة خطوة بخطوة. +- **سهولة المراقبة**: يسهل التتبع السهل لإكمال المهام وتقدم المشروع. + +## تنفيذ العملية التسلسلية + +لاستخدام العملية التسلسلية، قم بتجميع طاقمك وتعريف المهام بالترتيب الذي تحتاج إلى تنفيذها به. + +```python Code +from crewai import Crew, Process, Agent, Task, TaskOutput, CrewOutput + +# Define your agents +researcher = Agent( + role='Researcher', + goal='Conduct foundational research', + backstory='An experienced researcher with a passion for uncovering insights' +) +analyst = Agent( + role='Data Analyst', + goal='Analyze research findings', + backstory='A meticulous analyst with a knack for uncovering patterns' +) +writer = Agent( + role='Writer', + goal='Draft the final report', + backstory='A skilled writer with a talent for crafting compelling narratives' +) + +# Define your tasks +research_task = Task( + description='Gather relevant data...', + agent=researcher, + expected_output='Raw Data' +) +analysis_task = Task( + description='Analyze the data...', + agent=analyst, + expected_output='Data Insights' +) +writing_task = Task( + description='Compose the report...', + agent=writer, + expected_output='Final Report' +) + +# Form the crew with a sequential process +report_crew = Crew( + agents=[researcher, analyst, writer], + tasks=[research_task, analysis_task, writing_task], + process=Process.sequential +) + +# Execute the crew +result = report_crew.kickoff() + +# Accessing the type-safe output +task_output: TaskOutput = result.tasks[0].output +crew_output: CrewOutput = result.output +``` + +### ملاحظة: + +يجب أن يكون لكل مهمة في عملية تسلسلية وكيل مُعيّن. تأكد من أن كل `Task` تتضمن معامل `agent`. + +### سير العمل أثناء التنفيذ + +1. **المهمة الأولى**: في العملية التسلسلية، يكمل الوكيل الأول مهمته ويشير إلى الإكمال. +2. **المهام اللاحقة**: يلتقط الوكلاء مهامهم بناءً على نوع العملية، مع نتائج المهام السابقة أو التوجيهات التي تقود تنفيذهم. +3. **الإكمال**: تنتهي العملية بمجرد تنفيذ المهمة النهائية، مما يؤدي إلى إكمال المشروع. + +## الميزات المتقدمة + +### تفويض المهام + +في العمليات التسلسلية، إذا كان الوكيل لديه `allow_delegation` مُعيّن إلى `True`، يمكنه تفويض المهام إلى وكلاء آخرين في الطاقم. +يتم إعداد هذه الميزة تلقائياً عندما يكون هناك عدة وكلاء في الطاقم. + +### التنفيذ غير المتزامن + +يمكن تنفيذ المهام بشكل غير متزامن، مما يسمح بالمعالجة المتوازية عند الاقتضاء. +لإنشاء مهمة غير متزامنة، عيّن `async_execution=True` عند تعريف المهمة. + +### الذاكرة والتخزين المؤقت + +يدعم CrewAI كلاً من ميزتي الذاكرة والتخزين المؤقت: + +- **الذاكرة**: فعّلها بتعيين `memory=True` عند إنشاء الطاقم. يتيح هذا للوكلاء الاحتفاظ بالمعلومات عبر المهام. +- **التخزين المؤقت**: افتراضياً، التخزين المؤقت مفعّل. عيّن `cache=False` لتعطيله. + +### دوال الاستدعاء الراجع + +يمكنك تعيين دوال استدعاء راجع على مستوى المهمة والخطوة: + +- `task_callback`: يُنفذ بعد إكمال كل مهمة. +- `step_callback`: يُنفذ بعد كل خطوة في تنفيذ الوكيل. + +### مقاييس الاستخدام + +يتتبع CrewAI استخدام الرموز عبر جميع المهام والوكلاء. يمكنك الوصول إلى هذه المقاييس بعد التنفيذ. + +## أفضل الممارسات للعمليات التسلسلية + +1. **الترتيب مهم**: رتّب المهام بتسلسل منطقي حيث تبني كل مهمة على سابقتها. +2. **أوصاف مهام واضحة**: قدم أوصافاً مفصلة لكل مهمة لتوجيه الوكلاء بفعالية. +3. **اختيار الوكيل المناسب**: طابق مهارات وأدوار الوكلاء مع متطلبات كل مهمة. +4. **استخدم السياق**: استفد من سياق المهام السابقة لإبلاغ المهام اللاحقة. + +يضمن هذا التوثيق المحدث أن التفاصيل تعكس بدقة أحدث التغييرات في قاعدة الكود وتصف بوضوح كيفية الاستفادة من الميزات والإعدادات الجديدة. +تم الحفاظ على بساطة المحتوى ومباشرته لضمان سهولة الفهم. diff --git a/docs/ar/learn/streaming-crew-execution.mdx b/docs/ar/learn/streaming-crew-execution.mdx new file mode 100644 index 000000000..4dfe1859f --- /dev/null +++ b/docs/ar/learn/streaming-crew-execution.mdx @@ -0,0 +1,384 @@ +--- +title: بث تنفيذ الطاقم +description: بث المخرجات في الوقت الفعلي من تنفيذ طاقم CrewAI الخاص بك +icon: wave-pulse +mode: "wide" +--- + +## مقدمة + +يوفر CrewAI القدرة على بث المخرجات في الوقت الفعلي أثناء تنفيذ الطاقم، مما يتيح لك عرض النتائج فور توليدها بدلاً من انتظار اكتمال العملية بالكامل. هذه الميزة مفيدة بشكل خاص لبناء التطبيقات التفاعلية وتقديم تغذية راجعة للمستخدم ومراقبة العمليات طويلة التشغيل. + +## كيف يعمل البث + +عند تفعيل البث، يلتقط CrewAI استجابات LLM واستدعاءات الأدوات فور حدوثها، ويحزمها في أجزاء منظمة تتضمن سياقاً حول المهمة والوكيل المنفذ. يمكنك التكرار على هذه الأجزاء في الوقت الفعلي والوصول إلى النتيجة النهائية بمجرد اكتمال التنفيذ. + +## تفعيل البث + +لتفعيل البث، عيّن معامل `stream` إلى `True` عند إنشاء طاقمك: + +```python Code +from crewai import Agent, Crew, Task + +# Create your agents and tasks +researcher = Agent( + role="Research Analyst", + goal="Gather comprehensive information on topics", + backstory="You are an experienced researcher with excellent analytical skills.", +) + +task = Task( + description="Research the latest developments in AI", + expected_output="A detailed report on recent AI advancements", + agent=researcher, +) + +# Enable streaming +crew = Crew( + agents=[researcher], + tasks=[task], + stream=True # Enable streaming output +) +``` + +## البث المتزامن + +عند استدعاء `kickoff()` على طاقم مع تفعيل البث، يُرجع كائن `CrewStreamingOutput` يمكنك التكرار عليه لاستلام الأجزاء فور وصولها: + +```python Code +# Start streaming execution +streaming = crew.kickoff(inputs={"topic": "artificial intelligence"}) + +# Iterate over chunks as they arrive +for chunk in streaming: + print(chunk.content, end="", flush=True) + +# Access the final result after streaming completes +result = streaming.result +print(f"\n\nFinal output: {result.raw}") +``` + +### معلومات جزء البث + +يوفر كل جزء سياقاً غنياً حول التنفيذ: + +```python Code +streaming = crew.kickoff(inputs={"topic": "AI"}) + +for chunk in streaming: + print(f"Task: {chunk.task_name} (index {chunk.task_index})") + print(f"Agent: {chunk.agent_role}") + print(f"Content: {chunk.content}") + print(f"Type: {chunk.chunk_type}") # TEXT or TOOL_CALL + if chunk.tool_call: + print(f"Tool: {chunk.tool_call.tool_name}") + print(f"Arguments: {chunk.tool_call.arguments}") +``` + +### الوصول إلى نتائج البث + +يوفر كائن `CrewStreamingOutput` عدة خصائص مفيدة: + +```python Code +streaming = crew.kickoff(inputs={"topic": "AI"}) + +# Iterate and collect chunks +for chunk in streaming: + print(chunk.content, end="", flush=True) + +# After iteration completes +print(f"\nCompleted: {streaming.is_completed}") +print(f"Full text: {streaming.get_full_text()}") +print(f"All chunks: {len(streaming.chunks)}") +print(f"Final result: {streaming.result.raw}") +``` + +## البث غير المتزامن + +للتطبيقات غير المتزامنة، يمكنك استخدام إما `akickoff()` (async أصلي) أو `kickoff_async()` (قائم على الخيوط) مع التكرار غير المتزامن: + +### async أصلي مع `akickoff()` + +توفر طريقة `akickoff()` تنفيذاً غير متزامن أصلياً حقيقياً عبر السلسلة بالكامل: + +```python Code +import asyncio + +async def stream_crew(): + crew = Crew( + agents=[researcher], + tasks=[task], + stream=True + ) + + # Start native async streaming + streaming = await crew.akickoff(inputs={"topic": "AI"}) + + # Async iteration over chunks + async for chunk in streaming: + print(chunk.content, end="", flush=True) + + # Access final result + result = streaming.result + print(f"\n\nFinal output: {result.raw}") + +asyncio.run(stream_crew()) +``` + +### async قائم على الخيوط مع `kickoff_async()` + +للتكامل البسيط مع async أو التوافق مع الإصدارات السابقة: + +```python Code +import asyncio + +async def stream_crew(): + crew = Crew( + agents=[researcher], + tasks=[task], + stream=True + ) + + # Start thread-based async streaming + streaming = await crew.kickoff_async(inputs={"topic": "AI"}) + + # Async iteration over chunks + async for chunk in streaming: + print(chunk.content, end="", flush=True) + + # Access final result + result = streaming.result + print(f"\n\nFinal output: {result.raw}") + +asyncio.run(stream_crew()) +``` + + +لأحمال العمل عالية التزامن، يُوصى باستخدام `akickoff()` لأنه يستخدم async أصلي لتنفيذ المهام وعمليات الذاكرة واسترجاع المعرفة. راجع دليل [تشغيل الطاقم بشكل غير متزامن](/ar/learn/kickoff-async) لمزيد من التفاصيل. + + +## البث مع kickoff_for_each + +عند تنفيذ طاقم لمدخلات متعددة مع `kickoff_for_each()`، يعمل البث بشكل مختلف حسب ما إذا كنت تستخدم المتزامن أو غير المتزامن: + +### kickoff_for_each المتزامن + +مع `kickoff_for_each()` المتزامن، تحصل على قائمة كائنات `CrewStreamingOutput`، واحد لكل مدخل: + +```python Code +crew = Crew( + agents=[researcher], + tasks=[task], + stream=True +) + +inputs_list = [ + {"topic": "AI in healthcare"}, + {"topic": "AI in finance"} +] + +# Returns list of streaming outputs +streaming_outputs = crew.kickoff_for_each(inputs=inputs_list) + +# Iterate over each streaming output +for i, streaming in enumerate(streaming_outputs): + print(f"\n=== Input {i + 1} ===") + for chunk in streaming: + print(chunk.content, end="", flush=True) + + result = streaming.result + print(f"\n\nResult {i + 1}: {result.raw}") +``` + +### kickoff_for_each_async غير المتزامن + +مع `kickoff_for_each_async()` غير المتزامن، تحصل على `CrewStreamingOutput` واحد يُخرج أجزاء من جميع الأطقم فور وصولها بشكل متزامن: + +```python Code +import asyncio + +async def stream_multiple_crews(): + crew = Crew( + agents=[researcher], + tasks=[task], + stream=True + ) + + inputs_list = [ + {"topic": "AI in healthcare"}, + {"topic": "AI in finance"} + ] + + # Returns single streaming output for all crews + streaming = await crew.kickoff_for_each_async(inputs=inputs_list) + + # Chunks from all crews arrive as they're generated + async for chunk in streaming: + print(f"[{chunk.task_name}] {chunk.content}", end="", flush=True) + + # Access all results + results = streaming.results # List of CrewOutput objects + for i, result in enumerate(results): + print(f"\n\nResult {i + 1}: {result.raw}") + +asyncio.run(stream_multiple_crews()) +``` + +## أنواع أجزاء البث + +يمكن أن تكون الأجزاء من أنواع مختلفة، يُشار إليها بحقل `chunk_type`: + +### أجزاء TEXT + +محتوى نصي قياسي من استجابات LLM: + +```python Code +for chunk in streaming: + if chunk.chunk_type == StreamChunkType.TEXT: + print(chunk.content, end="", flush=True) +``` + +### أجزاء TOOL_CALL + +معلومات حول استدعاءات الأدوات الجارية: + +```python Code +for chunk in streaming: + if chunk.chunk_type == StreamChunkType.TOOL_CALL: + print(f"\nCalling tool: {chunk.tool_call.tool_name}") + print(f"Arguments: {chunk.tool_call.arguments}") +``` + +## مثال عملي: بناء واجهة مستخدم مع البث + +إليك مثالاً كاملاً يوضح كيفية بناء تطبيق تفاعلي مع البث: + +```python Code +import asyncio +from crewai import Agent, Crew, Task +from crewai.types.streaming import StreamChunkType + +async def interactive_research(): + # Create crew with streaming enabled + researcher = Agent( + role="Research Analyst", + goal="Provide detailed analysis on any topic", + backstory="You are an expert researcher with broad knowledge.", + ) + + task = Task( + description="Research and analyze: {topic}", + expected_output="A comprehensive analysis with key insights", + agent=researcher, + ) + + crew = Crew( + agents=[researcher], + tasks=[task], + stream=True, + verbose=False + ) + + # Get user input + topic = input("Enter a topic to research: ") + + print(f"\n{'='*60}") + print(f"Researching: {topic}") + print(f"{'='*60}\n") + + # Start streaming execution + streaming = await crew.kickoff_async(inputs={"topic": topic}) + + current_task = "" + async for chunk in streaming: + # Show task transitions + if chunk.task_name != current_task: + current_task = chunk.task_name + print(f"\n[{chunk.agent_role}] Working on: {chunk.task_name}") + print("-" * 60) + + # Display text chunks + if chunk.chunk_type == StreamChunkType.TEXT: + print(chunk.content, end="", flush=True) + + # Display tool calls + elif chunk.chunk_type == StreamChunkType.TOOL_CALL and chunk.tool_call: + print(f"\n🔧 Using tool: {chunk.tool_call.tool_name}") + + # Show final result + result = streaming.result + print(f"\n\n{'='*60}") + print("Analysis Complete!") + print(f"{'='*60}") + print(f"\nToken Usage: {result.token_usage}") + +asyncio.run(interactive_research()) +``` + +## حالات الاستخدام + +البث ذو قيمة خاصة لـ: + +- **التطبيقات التفاعلية**: تقديم تغذية راجعة فورية للمستخدمين أثناء عمل الوكلاء +- **المهام طويلة التشغيل**: عرض التقدم للبحث والتحليل أو توليد المحتوى +- **التصحيح والمراقبة**: مراقبة سلوك الوكلاء واتخاذ القرارات في الوقت الفعلي +- **تجربة المستخدم**: تقليل زمن الاستجابة المتصور بعرض نتائج تدريجية +- **لوحات المعلومات الحية**: بناء واجهات مراقبة تعرض حالة تنفيذ الطاقم + +## الإلغاء وتنظيف الموارد + +يدعم `CrewStreamingOutput` الإلغاء السلس بحيث يتوقف العمل الجاري فوراً عند انقطاع اتصال المستهلك. + +### مدير السياق غير المتزامن + +```python Code +streaming = await crew.akickoff(inputs={"topic": "AI"}) + +async with streaming: + async for chunk in streaming: + print(chunk.content, end="", flush=True) +``` + +### الإلغاء الصريح + +```python Code +streaming = await crew.akickoff(inputs={"topic": "AI"}) +try: + async for chunk in streaming: + print(chunk.content, end="", flush=True) +finally: + await streaming.aclose() # غير متزامن + # streaming.close() # المكافئ المتزامن +``` + +بعد الإلغاء، يكون كل من `streaming.is_cancelled` و `streaming.is_completed` بقيمة `True`. كل من `aclose()` و `close()` متساويان القوة. + +## ملاحظات مهمة + +- يفعّل البث تلقائياً بث LLM لجميع الوكلاء في الطاقم +- يجب التكرار عبر جميع الأجزاء قبل الوصول إلى خاصية `.result` +- لـ `kickoff_for_each_async()` مع البث، استخدم `.results` (بصيغة الجمع) للحصول على جميع المخرجات +- يضيف البث حملاً ضئيلاً ويمكن أن يحسن الأداء المتصور فعلياً +- يتضمن كل جزء سياقاً كاملاً (المهمة، الوكيل، نوع الجزء) لواجهات مستخدم غنية + +## معالجة الأخطاء + +التعامل مع الأخطاء أثناء تنفيذ البث: + +```python Code +streaming = crew.kickoff(inputs={"topic": "AI"}) + +try: + for chunk in streaming: + print(chunk.content, end="", flush=True) + + result = streaming.result + print(f"\nSuccess: {result.raw}") + +except Exception as e: + print(f"\nError during streaming: {e}") + if streaming.is_completed: + print("Streaming completed but an error occurred") +``` + +من خلال الاستفادة من البث، يمكنك بناء تطبيقات أكثر استجابة وتفاعلية مع CrewAI، مما يوفر للمستخدمين رؤية فورية لتنفيذ الوكلاء والنتائج. diff --git a/docs/ar/learn/streaming-flow-execution.mdx b/docs/ar/learn/streaming-flow-execution.mdx new file mode 100644 index 000000000..de4575b1c --- /dev/null +++ b/docs/ar/learn/streaming-flow-execution.mdx @@ -0,0 +1,478 @@ +--- +title: بث تنفيذ التدفق +description: بث المخرجات في الوقت الفعلي من تنفيذ تدفق CrewAI الخاص بك +icon: wave-pulse +mode: "wide" +--- + +## مقدمة + +تدعم تدفقات CrewAI بث المخرجات، مما يتيح لك استلام تحديثات فورية أثناء تنفيذ تدفقك. تمكّنك هذه الميزة من بناء تطبيقات متجاوبة تعرض النتائج تدريجياً وتوفر تحديثات تقدم حية وتخلق تجربة مستخدم أفضل لسير العمل طويلة التشغيل. + +## كيف يعمل بث التدفق + +عند تفعيل البث في تدفق، يلتقط CrewAI ويبث المخرجات من أي أطقم أو استدعاءات LLM داخل التدفق. يقدم البث أجزاء منظمة تحتوي على المحتوى وسياق المهمة ومعلومات الوكيل مع تقدم التنفيذ. + +## تفعيل البث + +لتفعيل البث، عيّن خاصية `stream` إلى `True` في فئة التدفق الخاصة بك: + +```python Code +from crewai.flow.flow import Flow, listen, start +from crewai import Agent, Crew, Task + +class ResearchFlow(Flow): + stream = True # Enable streaming for the entire flow + + @start() + def initialize(self): + return {"topic": "AI trends"} + + @listen(initialize) + def research_topic(self, data): + researcher = Agent( + role="Research Analyst", + goal="Research topics thoroughly", + backstory="Expert researcher with analytical skills", + ) + + task = Task( + description="Research {topic} and provide insights", + expected_output="Detailed research findings", + agent=researcher, + ) + + crew = Crew( + agents=[researcher], + tasks=[task], + ) + + return crew.kickoff(inputs=data) +``` + +## البث المتزامن + +عند استدعاء `kickoff()` على تدفق مع تفعيل البث، يُرجع كائن `FlowStreamingOutput` يمكنك التكرار عليه: + +```python Code +flow = ResearchFlow() + +# Start streaming execution +streaming = flow.kickoff() + +# Iterate over chunks as they arrive +for chunk in streaming: + print(chunk.content, end="", flush=True) + +# Access the final result after streaming completes +result = streaming.result +print(f"\n\nFinal output: {result}") +``` + +### معلومات جزء البث + +يوفر كل جزء سياقاً حول مصدره في التدفق: + +```python Code +streaming = flow.kickoff() + +for chunk in streaming: + print(f"Agent: {chunk.agent_role}") + print(f"Task: {chunk.task_name}") + print(f"Content: {chunk.content}") + print(f"Type: {chunk.chunk_type}") # TEXT or TOOL_CALL +``` + +### الوصول إلى خصائص البث + +يوفر كائن `FlowStreamingOutput` خصائص وطرق مفيدة: + +```python Code +streaming = flow.kickoff() + +# Iterate and collect chunks +for chunk in streaming: + print(chunk.content, end="", flush=True) + +# After iteration completes +print(f"\nCompleted: {streaming.is_completed}") +print(f"Full text: {streaming.get_full_text()}") +print(f"Total chunks: {len(streaming.chunks)}") +print(f"Final result: {streaming.result}") +``` + +## البث غير المتزامن + +للتطبيقات غير المتزامنة، استخدم `kickoff_async()` مع التكرار غير المتزامن: + +```python Code +import asyncio + +async def stream_flow(): + flow = ResearchFlow() + + # Start async streaming + streaming = await flow.kickoff_async() + + # Async iteration over chunks + async for chunk in streaming: + print(chunk.content, end="", flush=True) + + # Access final result + result = streaming.result + print(f"\n\nFinal output: {result}") + +asyncio.run(stream_flow()) +``` + +## البث مع التدفقات متعددة الخطوات + +يعمل البث بسلاسة عبر خطوات تدفق متعددة، بما في ذلك التدفقات التي تنفذ أطقم متعددة: + +```python Code +from crewai.flow.flow import Flow, listen, start +from crewai import Agent, Crew, Task + +class MultiStepFlow(Flow): + stream = True + + @start() + def research_phase(self): + """First crew: Research the topic.""" + researcher = Agent( + role="Research Analyst", + goal="Gather comprehensive information", + backstory="Expert at finding relevant information", + ) + + task = Task( + description="Research AI developments in healthcare", + expected_output="Research findings on AI in healthcare", + agent=researcher, + ) + + crew = Crew(agents=[researcher], tasks=[task]) + result = crew.kickoff() + + self.state["research"] = result.raw + return result.raw + + @listen(research_phase) + def analysis_phase(self, research_data): + """Second crew: Analyze the research.""" + analyst = Agent( + role="Data Analyst", + goal="Analyze information and extract insights", + backstory="Expert at identifying patterns and trends", + ) + + task = Task( + description="Analyze this research: {research}", + expected_output="Key insights and trends", + agent=analyst, + ) + + crew = Crew(agents=[analyst], tasks=[task]) + return crew.kickoff(inputs={"research": research_data}) + + +# Stream across both phases +flow = MultiStepFlow() +streaming = flow.kickoff() + +current_step = "" +for chunk in streaming: + # Track which flow step is executing + if chunk.task_name != current_step: + current_step = chunk.task_name + print(f"\n\n=== {chunk.task_name} ===\n") + + print(chunk.content, end="", flush=True) + +result = streaming.result +print(f"\n\nFinal analysis: {result}") +``` + +## مثال عملي: لوحة معلومات التقدم + +إليك مثالاً كاملاً يوضح كيفية بناء لوحة معلومات تقدم مع البث: + +```python Code +import asyncio +from crewai.flow.flow import Flow, listen, start +from crewai import Agent, Crew, Task +from crewai.types.streaming import StreamChunkType + +class ResearchPipeline(Flow): + stream = True + + @start() + def gather_data(self): + researcher = Agent( + role="Data Gatherer", + goal="Collect relevant information", + backstory="Skilled at finding quality sources", + ) + + task = Task( + description="Gather data on renewable energy trends", + expected_output="Collection of relevant data points", + agent=researcher, + ) + + crew = Crew(agents=[researcher], tasks=[task]) + result = crew.kickoff() + self.state["data"] = result.raw + return result.raw + + @listen(gather_data) + def analyze_data(self, data): + analyst = Agent( + role="Data Analyst", + goal="Extract meaningful insights", + backstory="Expert at data analysis", + ) + + task = Task( + description="Analyze: {data}", + expected_output="Key insights and trends", + agent=analyst, + ) + + crew = Crew(agents=[analyst], tasks=[task]) + return crew.kickoff(inputs={"data": data}) + + +async def run_with_dashboard(): + flow = ResearchPipeline() + + print("="*60) + print("RESEARCH PIPELINE DASHBOARD") + print("="*60) + + streaming = await flow.kickoff_async() + + current_agent = "" + current_task = "" + chunk_count = 0 + + async for chunk in streaming: + chunk_count += 1 + + # Display phase transitions + if chunk.task_name != current_task: + current_task = chunk.task_name + current_agent = chunk.agent_role + print(f"\n\n📋 Phase: {current_task}") + print(f"👤 Agent: {current_agent}") + print("-" * 60) + + # Display text output + if chunk.chunk_type == StreamChunkType.TEXT: + print(chunk.content, end="", flush=True) + + # Display tool usage + elif chunk.chunk_type == StreamChunkType.TOOL_CALL and chunk.tool_call: + print(f"\n🔧 Tool: {chunk.tool_call.tool_name}") + + # Show completion summary + result = streaming.result + print(f"\n\n{'='*60}") + print("PIPELINE COMPLETE") + print(f"{'='*60}") + print(f"Total chunks: {chunk_count}") + print(f"Final output length: {len(str(result))} characters") + +asyncio.run(run_with_dashboard()) +``` + +## البث مع إدارة الحالة + +يعمل البث بشكل طبيعي مع إدارة حالة التدفق: + +```python Code +from pydantic import BaseModel + +class AnalysisState(BaseModel): + topic: str = "" + research: str = "" + insights: str = "" + +class StatefulStreamingFlow(Flow[AnalysisState]): + stream = True + + @start() + def research(self): + # State is available during streaming + topic = self.state.topic + print(f"Researching: {topic}") + + researcher = Agent( + role="Researcher", + goal="Research topics thoroughly", + backstory="Expert researcher", + ) + + task = Task( + description=f"Research {topic}", + expected_output="Research findings", + agent=researcher, + ) + + crew = Crew(agents=[researcher], tasks=[task]) + result = crew.kickoff() + + self.state.research = result.raw + return result.raw + + @listen(research) + def analyze(self, research): + # Access updated state + print(f"Analyzing {len(self.state.research)} chars of research") + + analyst = Agent( + role="Analyst", + goal="Extract insights", + backstory="Expert analyst", + ) + + task = Task( + description="Analyze: {research}", + expected_output="Key insights", + agent=analyst, + ) + + crew = Crew(agents=[analyst], tasks=[task]) + result = crew.kickoff(inputs={"research": research}) + + self.state.insights = result.raw + return result.raw + + +# Run with streaming +flow = StatefulStreamingFlow() +streaming = flow.kickoff(inputs={"topic": "quantum computing"}) + +for chunk in streaming: + print(chunk.content, end="", flush=True) + +result = streaming.result +print(f"\n\nFinal state:") +print(f"Topic: {flow.state.topic}") +print(f"Research length: {len(flow.state.research)}") +print(f"Insights length: {len(flow.state.insights)}") +``` + +## حالات الاستخدام + +بث التدفق ذو قيمة خاصة لـ: + +- **سير العمل متعددة المراحل**: عرض التقدم عبر مراحل البحث والتحليل والتوليف +- **خطوط الأنابيب المعقدة**: توفير رؤية لتدفقات معالجة البيانات طويلة التشغيل +- **التطبيقات التفاعلية**: بناء واجهات مستخدم متجاوبة تعرض النتائج الوسيطة +- **المراقبة والتصحيح**: مراقبة تنفيذ التدفق وتفاعلات الأطقم في الوقت الفعلي +- **تتبع التقدم**: إظهار المرحلة الحالية من سير العمل للمستخدمين +- **لوحات المعلومات الحية**: إنشاء واجهات مراقبة لتدفقات الإنتاج + +## أنواع أجزاء البث + +مثل بث الطاقم، يمكن أن تكون أجزاء التدفق من أنواع مختلفة: + +### أجزاء TEXT + +محتوى نصي قياسي من استجابات LLM: + +```python Code +for chunk in streaming: + if chunk.chunk_type == StreamChunkType.TEXT: + print(chunk.content, end="", flush=True) +``` + +### أجزاء TOOL_CALL + +معلومات حول استدعاءات الأدوات داخل التدفق: + +```python Code +for chunk in streaming: + if chunk.chunk_type == StreamChunkType.TOOL_CALL and chunk.tool_call: + print(f"\nTool: {chunk.tool_call.tool_name}") + print(f"Args: {chunk.tool_call.arguments}") +``` + +## معالجة الأخطاء + +التعامل مع الأخطاء بأناقة أثناء البث: + +```python Code +flow = ResearchFlow() +streaming = flow.kickoff() + +try: + for chunk in streaming: + print(chunk.content, end="", flush=True) + + result = streaming.result + print(f"\nSuccess! Result: {result}") + +except Exception as e: + print(f"\nError during flow execution: {e}") + if streaming.is_completed: + print("Streaming completed but flow encountered an error") +``` + +## الإلغاء وتنظيف الموارد + +يدعم `FlowStreamingOutput` الإلغاء السلس بحيث يتوقف العمل الجاري فوراً عند انقطاع اتصال المستهلك. + +### مدير السياق غير المتزامن + +```python Code +streaming = await flow.kickoff_async() + +async with streaming: + async for chunk in streaming: + print(chunk.content, end="", flush=True) +``` + +### الإلغاء الصريح + +```python Code +streaming = await flow.kickoff_async() +try: + async for chunk in streaming: + print(chunk.content, end="", flush=True) +finally: + await streaming.aclose() # غير متزامن + # streaming.close() # المكافئ المتزامن +``` + +بعد الإلغاء، يكون كل من `streaming.is_cancelled` و `streaming.is_completed` بقيمة `True`. كل من `aclose()` و `close()` متساويان القوة. + +## ملاحظات مهمة + +- يفعّل البث تلقائياً بث LLM لأي أطقم مستخدمة داخل التدفق +- يجب التكرار عبر جميع الأجزاء قبل الوصول إلى خاصية `.result` +- يعمل البث مع كل من حالة التدفق المنظمة وغير المنظمة +- يلتقط بث التدفق المخرجات من جميع الأطقم واستدعاءات LLM في التدفق +- يتضمن كل جزء سياقاً حول الوكيل والمهمة التي ولدته +- يضيف البث حملاً ضئيلاً لتنفيذ التدفق + +## الدمج مع تصور التدفق + +يمكنك دمج البث مع تصور التدفق لتوفير صورة كاملة: + +```python Code +# Generate flow visualization +flow = ResearchFlow() +flow.plot("research_flow") # Creates HTML visualization + +# Run with streaming +streaming = flow.kickoff() +for chunk in streaming: + print(chunk.content, end="", flush=True) + +result = streaming.result +print(f"\nFlow complete! View structure at: research_flow.html") +``` + +من خلال الاستفادة من بث التدفق، يمكنك بناء تطبيقات متطورة ومتجاوبة توفر للمستخدمين رؤية فورية لسير العمل المعقدة متعددة المراحل، مما يجعل أتمتة الذكاء الاصطناعي الخاصة بك أكثر شفافية وجاذبية. diff --git a/docs/ar/learn/tool-hooks.mdx b/docs/ar/learn/tool-hooks.mdx new file mode 100644 index 000000000..372db5924 --- /dev/null +++ b/docs/ar/learn/tool-hooks.mdx @@ -0,0 +1,480 @@ +--- +title: خطافات استدعاء الأدوات +description: تعلم كيفية استخدام خطافات استدعاء الأدوات لاعتراض وتعديل والتحكم في تنفيذ الأدوات في CrewAI +mode: "wide" +--- + +توفر خطافات استدعاء الأدوات تحكماً دقيقاً في تنفيذ الأدوات أثناء عمليات الوكيل. تتيح لك هذه الخطافات اعتراض استدعاءات الأدوات وتعديل المدخلات وتحويل المخرجات وتنفيذ فحوصات السلامة وإضافة تسجيل أو مراقبة شاملة. + +## نظرة عامة + +تُنفذ خطافات الأدوات في نقطتين حرجتين: +- **قبل استدعاء الأداة**: تعديل المدخلات، التحقق من المعاملات، أو حظر التنفيذ +- **بعد استدعاء الأداة**: تحويل النتائج، تنقية المخرجات، أو تسجيل تفاصيل التنفيذ + +## أنواع الخطافات + +### خطافات ما قبل استدعاء الأداة + +تُنفذ قبل كل تنفيذ أداة، ويمكن لهذه الخطافات: +- فحص وتعديل مدخلات الأداة +- حظر تنفيذ الأداة بناءً على شروط +- تنفيذ بوابات موافقة للعمليات الخطرة +- التحقق من المعاملات +- تسجيل استدعاءات الأدوات + +**التوقيع:** +```python +def before_hook(context: ToolCallHookContext) -> bool | None: + # Return False to block execution + # Return True or None to allow execution + ... +``` + +### خطافات ما بعد استدعاء الأداة + +تُنفذ بعد كل تنفيذ أداة، ويمكن لهذه الخطافات: +- تعديل أو تنقية نتائج الأداة +- إضافة بيانات وصفية أو تنسيق +- تسجيل نتائج التنفيذ +- تنفيذ التحقق من النتائج +- تحويل تنسيقات المخرجات + +**التوقيع:** +```python +def after_hook(context: ToolCallHookContext) -> str | None: + # Return modified result string + # Return None to keep original result + ... +``` + +## سياق خطاف الأداة + +يوفر كائن `ToolCallHookContext` وصولاً شاملاً لحالة تنفيذ الأداة: + +```python +class ToolCallHookContext: + tool_name: str # Name of the tool being called + tool_input: dict[str, Any] # Mutable tool input parameters + tool: CrewStructuredTool # Tool instance reference + agent: Agent | BaseAgent | None # Agent executing the tool + task: Task | None # Current task + crew: Crew | None # Crew instance + tool_result: str | None # Tool result (after hooks only) +``` + +### تعديل مدخلات الأداة + +**مهم:** قم دائماً بتعديل مدخلات الأداة في مكانها: + +```python +# ✅ Correct - modify in-place +def sanitize_input(context: ToolCallHookContext) -> None: + context.tool_input['query'] = context.tool_input['query'].lower() + +# ❌ Wrong - replaces dict reference +def wrong_approach(context: ToolCallHookContext) -> None: + context.tool_input = {'query': 'new query'} +``` + +## طرق التسجيل + +### 1. تسجيل الخطافات العامة + +تسجيل خطافات تنطبق على جميع استدعاءات الأدوات عبر جميع الأطقم: + +```python +from crewai.hooks import register_before_tool_call_hook, register_after_tool_call_hook + +def log_tool_call(context): + print(f"Tool: {context.tool_name}") + print(f"Input: {context.tool_input}") + return None # Allow execution + +register_before_tool_call_hook(log_tool_call) +``` + +### 2. التسجيل باستخدام المزخرفات + +استخدم المزخرفات لصياغة أنظف: + +```python +from crewai.hooks import before_tool_call, after_tool_call + +@before_tool_call +def block_dangerous_tools(context): + dangerous_tools = ['delete_database', 'drop_table', 'rm_rf'] + if context.tool_name in dangerous_tools: + print(f"⛔ Blocked dangerous tool: {context.tool_name}") + return False # Block execution + return None + +@after_tool_call +def sanitize_results(context): + if context.tool_result and "password" in context.tool_result.lower(): + return context.tool_result.replace("password", "[REDACTED]") + return None +``` + +### 3. خطافات نطاق الطاقم + +تسجيل خطافات لمثيل طاقم محدد: + +```python +@CrewBase +class MyProjCrew: + @before_tool_call_crew + def validate_tool_inputs(self, context): + # Only applies to this crew + if context.tool_name == "web_search": + if not context.tool_input.get('query'): + print("❌ Invalid search query") + return False + return None + + @after_tool_call_crew + def log_tool_results(self, context): + # Crew-specific tool logging + print(f"✅ {context.tool_name} completed") + return None + + @crew + def crew(self) -> Crew: + return Crew( + agents=self.agents, + tasks=self.tasks, + process=Process.sequential, + verbose=True + ) +``` + +## حالات الاستخدام الشائعة + +### 1. حواجز السلامة + +```python +@before_tool_call +def safety_check(context: ToolCallHookContext) -> bool | None: + destructive_tools = [ + 'delete_file', + 'drop_table', + 'remove_user', + 'system_shutdown' + ] + + if context.tool_name in destructive_tools: + print(f"🛑 Blocked destructive tool: {context.tool_name}") + return False + + sensitive_tools = ['send_email', 'post_to_social_media', 'charge_payment'] + if context.tool_name in sensitive_tools: + print(f"⚠️ Executing sensitive tool: {context.tool_name}") + + return None +``` + +### 2. بوابة الموافقة البشرية + +```python +@before_tool_call +def require_approval_for_actions(context: ToolCallHookContext) -> bool | None: + approval_required = [ + 'send_email', + 'make_purchase', + 'delete_file', + 'post_message' + ] + + if context.tool_name in approval_required: + response = context.request_human_input( + prompt=f"Approve {context.tool_name}?", + default_message=f"Input: {context.tool_input}\nType 'yes' to approve:" + ) + + if response.lower() != 'yes': + print(f"❌ Tool execution denied: {context.tool_name}") + return False + + return None +``` + +### 3. التحقق من المدخلات وتنقيتها + +```python +@before_tool_call +def validate_and_sanitize_inputs(context: ToolCallHookContext) -> bool | None: + if context.tool_name == 'web_search': + query = context.tool_input.get('query', '') + if len(query) < 3: + print("❌ Search query too short") + return False + context.tool_input['query'] = query.strip().lower() + + if context.tool_name == 'read_file': + path = context.tool_input.get('path', '') + if '..' in path or path.startswith('/'): + print("❌ Invalid file path") + return False + + return None +``` + +### 4. تنقية النتائج + +```python +@after_tool_call +def sanitize_sensitive_data(context: ToolCallHookContext) -> str | None: + if not context.tool_result: + return None + + import re + result = context.tool_result + + result = re.sub( + r'(api[_-]?key|token)["\']?\s*[:=]\s*["\']?[\w-]+', + r'\1: [REDACTED]', + result, + flags=re.IGNORECASE + ) + + result = re.sub( + r'\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b', + '[EMAIL-REDACTED]', + result + ) + + result = re.sub( + r'\b\d{4}[- ]?\d{4}[- ]?\d{4}[- ]?\d{4}\b', + '[CARD-REDACTED]', + result + ) + + return result +``` + +### 5. تحليلات استخدام الأدوات + +```python +import time +from collections import defaultdict + +tool_stats = defaultdict(lambda: {'count': 0, 'total_time': 0, 'failures': 0}) + +@before_tool_call +def start_timer(context: ToolCallHookContext) -> None: + context.tool_input['_start_time'] = time.time() + return None + +@after_tool_call +def track_tool_usage(context: ToolCallHookContext) -> None: + start_time = context.tool_input.get('_start_time', time.time()) + duration = time.time() - start_time + + tool_stats[context.tool_name]['count'] += 1 + tool_stats[context.tool_name]['total_time'] += duration + + if not context.tool_result or 'error' in context.tool_result.lower(): + tool_stats[context.tool_name]['failures'] += 1 + + print(f""" + 📊 Tool Stats for {context.tool_name}: + - Executions: {tool_stats[context.tool_name]['count']} + - Avg Time: {tool_stats[context.tool_name]['total_time'] / tool_stats[context.tool_name]['count']:.2f}s + - Failures: {tool_stats[context.tool_name]['failures']} + """) + + return None +``` + +### 6. تحديد المعدل + +```python +from collections import defaultdict +from datetime import datetime, timedelta + +tool_call_history = defaultdict(list) + +@before_tool_call +def rate_limit_tools(context: ToolCallHookContext) -> bool | None: + tool_name = context.tool_name + now = datetime.now() + + tool_call_history[tool_name] = [ + call_time for call_time in tool_call_history[tool_name] + if now - call_time < timedelta(minutes=1) + ] + + if len(tool_call_history[tool_name]) >= 10: + print(f"🚫 Rate limit exceeded for {tool_name}") + return False + + tool_call_history[tool_name].append(now) + return None +``` + +### 7. تخزين نتائج الأدوات مؤقتاً + +```python +import hashlib +import json + +tool_cache = {} + +def cache_key(tool_name: str, tool_input: dict) -> str: + """Generate cache key from tool name and input.""" + input_str = json.dumps(tool_input, sort_keys=True) + return hashlib.md5(f"{tool_name}:{input_str}".encode()).hexdigest() + +@before_tool_call +def check_cache(context: ToolCallHookContext) -> bool | None: + key = cache_key(context.tool_name, context.tool_input) + if key in tool_cache: + print(f"💾 Cache hit for {context.tool_name}") + return None + +@after_tool_call +def cache_result(context: ToolCallHookContext) -> None: + if context.tool_result: + key = cache_key(context.tool_name, context.tool_input) + tool_cache[key] = context.tool_result + print(f"💾 Cached result for {context.tool_name}") + return None +``` + +### 8. تسجيل التصحيح + +```python +@before_tool_call +def debug_tool_call(context: ToolCallHookContext) -> None: + print(f""" + 🔍 Tool Call Debug: + - Tool: {context.tool_name} + - Agent: {context.agent.role if context.agent else 'Unknown'} + - Task: {context.task.description[:50] if context.task else 'Unknown'}... + - Input: {context.tool_input} + """) + return None + +@after_tool_call +def debug_tool_result(context: ToolCallHookContext) -> None: + if context.tool_result: + result_preview = context.tool_result[:200] + print(f"✅ Result Preview: {result_preview}...") + else: + print("⚠️ No result returned") + return None +``` + +## إدارة الخطافات + +### إلغاء تسجيل الخطافات + +```python +from crewai.hooks import ( + unregister_before_tool_call_hook, + unregister_after_tool_call_hook +) + +def my_hook(context): + ... + +register_before_tool_call_hook(my_hook) +success = unregister_before_tool_call_hook(my_hook) +print(f"Unregistered: {success}") +``` + +### مسح الخطافات + +```python +from crewai.hooks import ( + clear_before_tool_call_hooks, + clear_after_tool_call_hooks, + clear_all_tool_call_hooks +) + +count = clear_before_tool_call_hooks() +print(f"Cleared {count} before hooks") + +before_count, after_count = clear_all_tool_call_hooks() +print(f"Cleared {before_count} before and {after_count} after hooks") +``` + +### عرض الخطافات المسجلة + +```python +from crewai.hooks import ( + get_before_tool_call_hooks, + get_after_tool_call_hooks +) + +before_hooks = get_before_tool_call_hooks() +after_hooks = get_after_tool_call_hooks() + +print(f"Registered: {len(before_hooks)} before, {len(after_hooks)} after") +``` + +## أفضل الممارسات + +1. **اجعل الخطافات مركزة**: يجب أن يكون لكل خطاف مسؤولية واحدة +2. **تجنب الحسابات الثقيلة**: تُنفذ الخطافات في كل استدعاء أداة +3. **تعامل مع الأخطاء بأناقة**: استخدم try-except لمنع فشل الخطافات +4. **استخدم تلميحات الأنواع**: استفد من `ToolCallHookContext` لدعم أفضل في بيئة التطوير +5. **وثّق شروط الحظر**: وضّح متى ولماذا تُحظر الأدوات +6. **اختبر الخطافات بشكل مستقل**: اختبر الخطافات وحدوياً قبل الاستخدام في الإنتاج +7. **امسح الخطافات في الاختبارات**: استخدم `clear_all_tool_call_hooks()` بين تشغيلات الاختبار +8. **عدّل في المكان**: قم دائماً بتعديل `context.tool_input` في مكانه، ولا تستبدله +9. **سجّل القرارات المهمة**: خاصة عند حظر تنفيذ الأدوات +10. **راعِ الأداء**: خزّن عمليات التحقق المكلفة مؤقتاً عند الإمكان + +## معالجة الأخطاء + +```python +@before_tool_call +def safe_validation(context: ToolCallHookContext) -> bool | None: + try: + if not validate_input(context.tool_input): + return False + except Exception as e: + print(f"⚠️ Hook error: {e}") + return None # Allow execution despite error +``` + +## أمان الأنواع + +```python +from crewai.hooks import ToolCallHookContext, BeforeToolCallHookType, AfterToolCallHookType + +def my_before_hook(context: ToolCallHookContext) -> bool | None: + return None + +def my_after_hook(context: ToolCallHookContext) -> str | None: + return None + +register_before_tool_call_hook(my_before_hook) +register_after_tool_call_hook(my_after_hook) +``` + +## استكشاف الأخطاء وإصلاحها + +### الخطاف لا يُنفذ +- تحقق من أن الخطاف مسجل قبل تنفيذ الطاقم +- تحقق مما إذا كان خطاف سابق أرجع `False` (يحظر التنفيذ والخطافات اللاحقة) +- تأكد من أن توقيع الخطاف يطابق النوع المتوقع + +### تعديلات المدخلات لا تعمل +- استخدم التعديلات في المكان: `context.tool_input['key'] = value` +- لا تستبدل القاموس: `context.tool_input = {}` + +### تعديلات النتائج لا تعمل +- أرجع السلسلة النصية المعدلة من خطافات ما بعد +- إرجاع `None` يحتفظ بالنتيجة الأصلية +- تأكد من أن الأداة أرجعت نتيجة فعلاً + +### أداة محظورة بشكل غير متوقع +- تحقق من جميع خطافات ما قبل بحثاً عن شروط حظر +- تحقق من ترتيب تنفيذ الخطافات +- أضف تسجيل تصحيح لتحديد الخطاف الذي يحظر + +## الخاتمة + +توفر خطافات استدعاء الأدوات إمكانيات قوية للتحكم في تنفيذ الأدوات ومراقبتها في CrewAI. استخدمها لتنفيذ حواجز السلامة وبوابات الموافقة والتحقق من المدخلات وتنقية النتائج والتسجيل والتحليلات. مع معالجة الأخطاء المناسبة وأمان الأنواع، تُمكّن الخطافات أنظمة وكلاء آمنة وجاهزة للإنتاج مع مراقبة شاملة. diff --git a/docs/ar/learn/using-annotations.mdx b/docs/ar/learn/using-annotations.mdx new file mode 100644 index 000000000..2b7487a16 --- /dev/null +++ b/docs/ar/learn/using-annotations.mdx @@ -0,0 +1,151 @@ +--- +title: "استخدام التعليقات التوضيحية في crew.py" +description: "تعلم كيفية استخدام التعليقات التوضيحية لتنظيم الوكلاء والمهام والمكونات بشكل صحيح في CrewAI" +icon: "at" +mode: "wide" +--- + +يشرح هذا الدليل كيفية استخدام التعليقات التوضيحية للإشارة بشكل صحيح إلى **الوكلاء** و**المهام** والمكونات الأخرى في ملف `crew.py`. + +## مقدمة + +تُستخدم التعليقات التوضيحية في إطار عمل CrewAI لتزيين الفئات والطرق، مما يوفر بيانات وصفية ووظائف للمكونات المختلفة في طاقمك. تساعد هذه التعليقات التوضيحية في تنظيم وهيكلة الكود الخاص بك، مما يجعله أكثر قابلية للقراءة والصيانة. + +## التعليقات التوضيحية المتاحة + +يوفر إطار عمل CrewAI التعليقات التوضيحية التالية: + +- `@CrewBase`: تُستخدم لتزيين فئة الطاقم الرئيسية. +- `@agent`: تزين الطرق التي تعرّف وتُرجع كائنات Agent. +- `@task`: تزين الطرق التي تعرّف وتُرجع كائنات Task. +- `@crew`: تزين الطريقة التي تنشئ وتُرجع كائن Crew. +- `@llm`: تزين الطرق التي تهيئ وتُرجع كائنات نماذج اللغة. +- `@tool`: تزين الطرق التي تهيئ وتُرجع كائنات الأدوات. +- `@callback`: تُستخدم لتعريف طرق الاستدعاء الراجع. +- `@output_json`: تُستخدم للطرق التي تُخرج بيانات JSON. +- `@output_pydantic`: تُستخدم للطرق التي تُخرج نماذج Pydantic. +- `@cache_handler`: تُستخدم لتعريف طرق معالجة التخزين المؤقت. + +## أمثلة الاستخدام + +لنمر عبر أمثلة لكيفية استخدام هذه التعليقات التوضيحية: + +### 1. فئة الطاقم الأساسية + +```python +@CrewBase +class LinkedinProfileCrew(): + """LinkedinProfile crew""" + agents_config = 'config/agents.yaml' + tasks_config = 'config/tasks.yaml' +``` + +تُستخدم التعليقة التوضيحية `@CrewBase` لتزيين فئة الطاقم الرئيسية. تحتوي هذه الفئة عادةً على الإعدادات والطرق لإنشاء الوكلاء والمهام والطاقم نفسه. + + +`@CrewBase` تفعل أكثر من مجرد تسجيل الفئة: + +- **تمهيد الإعدادات:** تبحث عن `agents_config` و `tasks_config` (القيمة الافتراضية `config/agents.yaml` و `config/tasks.yaml`) بجانب ملف الفئة، وتحملها عند الإنشاء، وتتراجع بأمان إلى قواميس فارغة إذا كانت الملفات مفقودة. +- **تنسيق المزخرفات:** تحتفظ بمراجع محفوظة لكل طريقة مُعلّمة بـ `@agent` أو `@task` أو `@before_kickoff` أو `@after_kickoff` بحيث يتم إنشاؤها مرة واحدة لكل طاقم وتُنفذ بترتيب الإعلان. +- **ربط الخطافات:** تربط تلقائياً خطافات التشغيل المحفوظة بكائن `Crew` المُرجع من طريقة `@crew`، مما يجعلها تعمل قبل وبعد `.kickoff()`. +- **تكامل MCP:** عندما تعرّف الفئة `mcp_server_params`، ينشئ `get_mcp_tools()` بكسل محول MCP server، ويملأ الأدوات المُعلنة، ويوقف خطاف ما بعد التشغيل الداخلي المحول. راجع [نظرة عامة على MCP](/ar/mcp/overview) لتفاصيل إعداد المحول. + + +### 2. تعريف الأداة + +```python +@tool +def myLinkedInProfileTool(self): + return LinkedInProfileTool() +``` + +تُستخدم التعليقة التوضيحية `@tool` لتزيين الطرق التي تُرجع كائنات أدوات. يمكن للوكلاء استخدام هذه الأدوات لأداء مهام محددة. + +### 3. تعريف 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") +``` + +تُستخدم التعليقة التوضيحية `@llm` لتزيين الطرق التي تهيئ وتُرجع كائنات نماذج اللغة. تستخدم هذه النماذج من قبل الوكلاء لمهام معالجة اللغة الطبيعية. + +### 4. تعريف الوكيل + +```python +@agent +def researcher(self) -> Agent: + return Agent( + config=self.agents_config['researcher'] + ) +``` + +تُستخدم التعليقة التوضيحية `@agent` لتزيين الطرق التي تعرّف وتُرجع كائنات Agent. + +### 5. تعريف المهمة + +```python +@task +def research_task(self) -> Task: + return Task( + config=self.tasks_config['research_linkedin_task'], + agent=self.researcher() + ) +``` + +تُستخدم التعليقة التوضيحية `@task` لتزيين الطرق التي تعرّف وتُرجع كائنات Task. تحدد هذه الطرق إعداد المهمة والوكيل المسؤول عنها. + +### 6. إنشاء الطاقم + +```python +@crew +def crew(self) -> Crew: + """Creates the LinkedinProfile crew""" + return Crew( + agents=self.agents, + tasks=self.tasks, + process=Process.sequential, + verbose=True + ) +``` + +تُستخدم التعليقة التوضيحية `@crew` لتزيين الطريقة التي تنشئ وتُرجع كائن `Crew`. تجمع هذه الطريقة جميع المكونات (الوكلاء والمهام) في طاقم وظيفي. + +## إعداد YAML + +تُخزن إعدادات الوكلاء عادةً في ملف YAML. إليك مثالاً على كيفية ظهور ملف `agents.yaml` لوكيل الباحث: + +```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 +``` + +يتوافق إعداد YAML هذا مع وكيل الباحث المُعرّف في فئة `LinkedinProfileCrew`. يحدد الإعداد دور الوكيل وهدفه وخلفيته وخصائص أخرى مثل LLM والأدوات التي يستخدمها. + +لاحظ كيف يتوافق `llm` و `tools` في ملف YAML مع الطرق المزينة بـ `@llm` و `@tool` في فئة Python. + +## أفضل الممارسات + +- **تسمية متسقة**: استخدم اصطلاحات تسمية واضحة ومتسقة لطرقك. على سبيل المثال، يمكن تسمية طرق الوكلاء بأسماء أدوارهم (مثل researcher، reporting_analyst). +- **متغيرات البيئة**: استخدم متغيرات البيئة للمعلومات الحساسة مثل مفاتيح API. +- **المرونة**: صمم طاقمك ليكون مرناً بالسماح بإضافة أو إزالة الوكلاء والمهام بسهولة. +- **توافق YAML-الكود**: تأكد من أن الأسماء والهياكل في ملفات YAML تتوافق بشكل صحيح مع الطرق المزينة في كود Python الخاص بك. + +باتباع هذه الإرشادات واستخدام التعليقات التوضيحية بشكل صحيح، يمكنك إنشاء أطقم منظمة جيداً وسهلة الصيانة باستخدام إطار عمل CrewAI. diff --git a/docs/ar/mcp/dsl-integration.mdx b/docs/ar/mcp/dsl-integration.mdx new file mode 100644 index 000000000..392570e1f --- /dev/null +++ b/docs/ar/mcp/dsl-integration.mdx @@ -0,0 +1,349 @@ +--- +title: تكامل MCP DSL +description: تعلم كيفية استخدام صياغة DSL البسيطة في CrewAI لدمج خوادم MCP مباشرة مع وكلائك باستخدام حقل mcps. +icon: code +mode: "wide" +--- + +## نظرة عامة + +يوفر تكامل MCP DSL (لغة المجال المحددة) في CrewAI **الطريقة الأبسط** لربط وكلائك بخوادم MCP (بروتوكول سياق النموذج). ما عليك سوى إضافة حقل `mcps` إلى وكيلك وسيتعامل CrewAI مع كل التعقيدات تلقائياً. + + + هذا هو **النهج الموصى به** لمعظم حالات استخدام MCP. للسيناريوهات المتقدمة + التي تتطلب إدارة اتصال يدوية، راجع + [MCPServerAdapter](/ar/mcp/overview#advanced-mcpserveradapter). + + +## الاستخدام الأساسي + +أضف خوادم MCP إلى وكيلك باستخدام حقل `mcps`: + +```python +from crewai import Agent + +agent = Agent( + role="Research Assistant", + goal="Help with research and analysis tasks", + backstory="Expert assistant with access to advanced research tools", + mcps=[ + "https://mcp.exa.ai/mcp?api_key=your_key&profile=research" + ] +) + +# MCP tools are now automatically available! +# No need for manual connection management or tool configuration +``` + +## تنسيقات المراجع المدعومة + +### خوادم MCP البعيدة الخارجية + +```python +# Basic HTTPS server +"https://api.example.com/mcp" + +# Server with authentication +"https://mcp.exa.ai/mcp?api_key=your_key&profile=your_profile" + +# Server with custom path +"https://services.company.com/api/v1/mcp" +``` + +### اختيار أدوات محددة + +استخدم صياغة `#` لاختيار أدوات محددة من خادم: + +```python +# Get only the forecast tool from weather server +"https://weather.api.com/mcp#get_forecast" + +# Get only the search tool from Exa +"https://mcp.exa.ai/mcp?api_key=your_key#web_search_exa" +``` + +### تكاملات MCP المتصلة + +اربط خوادم MCP من كتالوج CrewAI أو أحضر خوادمك الخاصة. بمجرد الاتصال في حسابك، أشر إليها بالمعرف المختصر: + +```python +# Connected MCP with all tools +"snowflake" + +# Specific tool from a connected MCP +"stripe#list_invoices" + +# Multiple connected MCPs +mcps=[ + "snowflake", + "stripe", + "github" +] +``` + +## مثال كامل + +إليك مثالاً كاملاً يستخدم خوادم MCP متعددة: + +```python +from crewai import Agent, Task, Crew, Process + +# Create agent with multiple MCP sources +multi_source_agent = Agent( + role="Multi-Source Research Analyst", + goal="Conduct comprehensive research using multiple data sources", + backstory="""Expert researcher with access to web search, weather data, + financial information, and academic research tools""", + mcps=[ + # External MCP servers + "https://mcp.exa.ai/mcp?api_key=your_exa_key&profile=research", + "https://weather.api.com/mcp#get_current_conditions", + + # Connected MCPs from catalog + "snowflake", + "stripe#list_invoices", + "github#search_repositories" + ] +) + +# Create comprehensive research task +research_task = Task( + description="""Research the impact of AI agents on business productivity. + Include current weather impacts on remote work, financial market trends, + and recent academic publications on AI agent frameworks.""", + expected_output="""Comprehensive report covering: + 1. AI agent business impact analysis + 2. Weather considerations for remote work + 3. Financial market trends related to AI + 4. Academic research citations and insights + 5. Competitive landscape analysis""", + agent=multi_source_agent +) + +# Create and execute crew +research_crew = Crew( + agents=[multi_source_agent], + tasks=[research_task], + process=Process.sequential, + verbose=True +) + +result = research_crew.kickoff() +print(f"Research completed with {len(multi_source_agent.mcps)} MCP data sources") +``` + +## تسمية الأدوات والتنظيم + +يتعامل CrewAI تلقائياً مع تسمية الأدوات لمنع التعارضات: + +```python +# Original MCP server has tools: "search", "analyze" +# CrewAI creates tools: "mcp_exa_ai_search", "mcp_exa_ai_analyze" + +agent = Agent( + role="Tool Organization Demo", + goal="Show how tool naming works", + backstory="Demonstrates automatic tool organization", + mcps=[ + "https://mcp.exa.ai/mcp?api_key=key", # Tools: mcp_exa_ai_* + "https://weather.service.com/mcp", # Tools: weather_service_com_* + "snowflake" # Tools: snowflake_* + ] +) + +# Each server's tools get unique prefixes based on the server name +# This prevents naming conflicts between different MCP servers +``` + +## معالجة الأخطاء والمرونة + +صُمم MCP DSL ليكون متيناً وسهل الاستخدام: + +### التعامل الأنيق مع فشل الخادم + +```python +agent = Agent( + role="Resilient Researcher", + goal="Research despite server issues", + backstory="Experienced researcher who adapts to available tools", + mcps=[ + "https://primary-server.com/mcp", # Primary data source + "https://backup-server.com/mcp", # Backup if primary fails + "https://unreachable-server.com/mcp", # Will be skipped with warning + "snowflake" # Connected MCP from catalog + ] +) + +# Agent will: +# 1. Successfully connect to working servers +# 2. Log warnings for failing servers +# 3. Continue with available tools +# 4. Not crash or hang on server failures +``` + +### حماية المهلة الزمنية + +جميع عمليات MCP لها مهلات زمنية مدمجة: + +- **مهلة الاتصال**: 10 ثوانٍ +- **مهلة تنفيذ الأداة**: 30 ثانية +- **مهلة الاكتشاف**: 15 ثانية + +```python +# These servers will timeout gracefully if unresponsive +mcps=[ + "https://slow-server.com/mcp", # Will timeout after 10s if unresponsive + "https://overloaded-api.com/mcp" # Will timeout if discovery takes > 15s +] +``` + +## ميزات الأداء + +### التخزين المؤقت التلقائي + +تُخزن مخططات الأدوات مؤقتاً لمدة 5 دقائق لتحسين الأداء: + +```python +# First agent creation - discovers tools from server +agent1 = Agent(role="First", goal="Test", backstory="Test", + mcps=["https://api.example.com/mcp"]) + +# Second agent creation (within 5 minutes) - uses cached tool schemas +agent2 = Agent(role="Second", goal="Test", backstory="Test", + mcps=["https://api.example.com/mcp"]) # Much faster! +``` + +### الاتصالات حسب الطلب + +تُنشأ اتصالات الأدوات فقط عند استخدام الأدوات فعلياً: + +```python +# Agent creation is fast - no MCP connections made yet +agent = Agent( + role="On-Demand Agent", + goal="Use tools efficiently", + backstory="Efficient agent that connects only when needed", + mcps=["https://api.example.com/mcp"] +) + +# MCP connection is made only when a tool is actually executed +# This minimizes connection overhead and improves startup performance +``` + +## التكامل مع الميزات الموجودة + +تعمل أدوات MCP بسلاسة مع ميزات CrewAI الأخرى: + +```python +from crewai.tools import BaseTool + +class CustomTool(BaseTool): + name: str = "custom_analysis" + description: str = "Custom analysis tool" + + def _run(self, **kwargs): + return "Custom analysis result" + +agent = Agent( + role="Full-Featured Agent", + goal="Use all available tool types", + backstory="Agent with comprehensive tool access", + + # All tool types work together + tools=[CustomTool()], # Custom tools + apps=["gmail", "slack"], # Platform integrations + mcps=[ # MCP servers + "https://mcp.exa.ai/mcp?api_key=key", + "snowflake" + ], + + verbose=True, + max_iter=15 +) +``` + +## أفضل الممارسات + +### 1. استخدم أدوات محددة عند الإمكان + +```python +# Good - only get the tools you need +mcps=["https://weather.api.com/mcp#get_forecast"] + +# Less efficient - gets all tools from server +mcps=["https://weather.api.com/mcp"] +``` + +### 2. تعامل مع المصادقة بأمان + +```python +import os + +# Store API keys in environment variables +exa_key = os.getenv("EXA_API_KEY") +exa_profile = os.getenv("EXA_PROFILE") + +agent = Agent( + role="Secure Agent", + goal="Use MCP tools securely", + backstory="Security-conscious agent", + mcps=[f"https://mcp.exa.ai/mcp?api_key={exa_key}&profile={exa_profile}"] +) +``` + +### 3. خطط لفشل الخادم + +```python +# Always include backup options +mcps=[ + "https://primary-api.com/mcp", # Primary choice + "https://backup-api.com/mcp", # Backup option + "snowflake" # Connected MCP fallback +] +``` + +### 4. استخدم أدواراً وصفية للوكلاء + +```python +agent = Agent( + role="Weather-Enhanced Market Analyst", + goal="Analyze markets considering weather impacts", + backstory="Financial analyst with access to weather data for agricultural market insights", + mcps=[ + "https://weather.service.com/mcp#get_forecast", + "stripe#list_invoices" + ] +) +``` + +## استكشاف الأخطاء وإصلاحها + +### المشاكل الشائعة + +**لم يتم اكتشاف أدوات:** + +```python +# Check your MCP server URL and authentication +# Verify the server is running and accessible +mcps=["https://mcp.example.com/mcp?api_key=valid_key"] +``` + +**انتهاء مهلة الاتصال:** + +```python +# Server may be slow or overloaded +# CrewAI will log warnings and continue with other servers +# Check server status or try backup servers +``` + +**فشل المصادقة:** + +```python +# Verify API keys and credentials +# Check server documentation for required parameters +# Ensure query parameters are properly URL encoded +``` + +## متقدم: MCPServerAdapter + +للسيناريوهات المعقدة التي تتطلب إدارة اتصال يدوية، استخدم فئة `MCPServerAdapter` من `crewai-tools`. استخدام مدير سياق Python (تعليمة `with`) هو النهج الموصى به لأنه يتعامل تلقائياً مع بدء وإيقاف الاتصال بخادم MCP. diff --git a/docs/ar/mcp/multiple-servers.mdx b/docs/ar/mcp/multiple-servers.mdx new file mode 100644 index 000000000..14e2d4681 --- /dev/null +++ b/docs/ar/mcp/multiple-servers.mdx @@ -0,0 +1,65 @@ +--- +title: الاتصال بخوادم MCP متعددة +description: تعلم كيفية استخدام MCPServerAdapter في CrewAI للاتصال بخوادم MCP متعددة بشكل متزامن وتجميع أدواتها. +icon: layer-group +mode: "wide" +--- + +## نظرة عامة + +يتيح لك `MCPServerAdapter` في `crewai-tools` الاتصال بخوادم MCP متعددة بشكل متزامن. هذا مفيد عندما يحتاج وكلاؤك للوصول إلى أدوات موزعة عبر خدمات أو بيئات مختلفة. يجمع المحول الأدوات من جميع الخوادم المحددة، مما يجعلها متاحة لوكلاء CrewAI. + +## الإعداد + +للاتصال بخوادم متعددة، توفر قائمة من قواميس معاملات الخادم لـ `MCPServerAdapter`. يجب أن يعرّف كل قاموس في القائمة معاملات خادم MCP واحد. + +تتضمن أنواع النقل المدعومة لكل خادم في القائمة `stdio` و `sse` و `streamable-http`. + +```python +from crewai import Agent, Task, Crew, Process +from crewai_tools import MCPServerAdapter +from mcp import StdioServerParameters # Needed for Stdio example + +# Define parameters for multiple MCP servers +server_params_list = [ + # Streamable HTTP Server + { + "url": "http://localhost:8001/mcp", + "transport": "streamable-http" + }, + # SSE Server + { + "url": "http://localhost:8000/sse", + "transport": "sse" + }, + # StdIO Server + StdioServerParameters( + command="python3", + args=["servers/your_stdio_server.py"], + env={"UV_PYTHON": "3.12", **os.environ}, + ) +] + +try: + with MCPServerAdapter(server_params_list) as aggregated_tools: + print(f"Available aggregated tools: {[tool.name for tool in aggregated_tools]}") + + multi_server_agent = Agent( + role="Versatile Assistant", + goal="Utilize tools from local Stdio, remote SSE, and remote HTTP MCP servers.", + backstory="An AI agent capable of leveraging a diverse set of tools from multiple sources.", + tools=aggregated_tools, # All tools are available here + verbose=True, + ) + + ... # Your other agent, tasks, and crew code here + +except Exception as e: + print(f"Error connecting to or using multiple MCP servers (Managed): {e}") + print("Ensure all MCP servers are running and accessible with correct configurations.") + +``` + +## إدارة الاتصال + +عند استخدام مدير السياق (تعليمة `with`)، يتعامل `MCPServerAdapter` مع دورة حياة جميع الاتصالات بخوادم MCP المُعدة (البدء والإيقاف). هذا يبسط إدارة الموارد ويضمن إغلاق جميع الاتصالات بشكل صحيح عند الخروج من السياق. diff --git a/docs/ar/mcp/overview.mdx b/docs/ar/mcp/overview.mdx new file mode 100644 index 000000000..ecb1204ee --- /dev/null +++ b/docs/ar/mcp/overview.mdx @@ -0,0 +1,690 @@ +--- +title: "خوادم MCP كأدوات في CrewAI" +description: "تعلم كيفية دمج خوادم MCP كأدوات في وكلاء CrewAI باستخدام مكتبة `crewai-tools`." +icon: plug +mode: "wide" +--- + +## نظرة عامة + +يوفر [بروتوكول سياق النموذج](https://modelcontextprotocol.io/introduction) (MCP) طريقة موحدة لوكلاء الذكاء الاصطناعي لتوفير سياق لنماذج اللغة الكبيرة من خلال التواصل مع خدمات خارجية تُعرف بخوادم MCP. + +يقدم CrewAI **نهجين** لتكامل MCP: + +### تكامل DSL البسيط (الموصى به) + +استخدم حقل `mcps` مباشرة على الوكلاء لتكامل سلس مع أدوات MCP. يدعم DSL كلاً من **المراجع النصية** (للإعداد السريع) و**الإعدادات المنظمة** (للتحكم الكامل). + +#### المراجع النصية (إعداد سريع) + +مثالية لخوادم HTTPS البعيدة وتكاملات MCP المتصلة من كتالوج CrewAI: + +```python +from crewai import Agent + +agent = Agent( + role="Research Analyst", + goal="Research and analyze information", + backstory="Expert researcher with access to external tools", + mcps=[ + "https://mcp.exa.ai/mcp?api_key=your_key", # External MCP server + "https://api.weather.com/mcp#get_forecast", # Specific tool from server + "snowflake", # Connected MCP from catalog + "stripe#list_invoices" # Specific tool from connected MCP + ] +) +# MCP tools are now automatically available to your agent! +``` + +#### الإعدادات المنظمة (تحكم كامل) + +للتحكم الكامل في إعدادات الاتصال وتصفية الأدوات وجميع أنواع النقل: + +```python +from crewai import Agent +from crewai.mcp import MCPServerStdio, MCPServerHTTP, MCPServerSSE +from crewai.mcp.filters import create_static_tool_filter + +agent = Agent( + role="Advanced Research Analyst", + goal="Research with full control over MCP connections", + backstory="Expert researcher with advanced tool access", + mcps=[ + # Stdio transport for local servers + MCPServerStdio( + command="npx", + args=["-y", "@modelcontextprotocol/server-filesystem"], + env={"API_KEY": "your_key"}, + tool_filter=create_static_tool_filter( + allowed_tool_names=["read_file", "list_directory"] + ), + cache_tools_list=True, + ), + # HTTP/Streamable HTTP transport for remote servers + MCPServerHTTP( + url="https://api.example.com/mcp", + headers={"Authorization": "Bearer your_token"}, + streamable=True, + cache_tools_list=True, + ), + # SSE transport for real-time streaming + MCPServerSSE( + url="https://stream.example.com/mcp/sse", + headers={"Authorization": "Bearer your_token"}, + ), + ] +) +``` + +### متقدم: MCPServerAdapter (للسيناريوهات المعقدة) + +لحالات الاستخدام المتقدمة التي تتطلب إدارة اتصال يدوية، توفر مكتبة `crewai-tools` فئة `MCPServerAdapter`. + +ندعم حالياً آليات النقل التالية: + +- **Stdio**: للخوادم المحلية (التواصل عبر الإدخال/الإخراج القياسي بين العمليات على نفس الجهاز) +- **Server-Sent Events (SSE)**: للخوادم البعيدة (بث بيانات أحادي الاتجاه في الوقت الفعلي من الخادم إلى العميل عبر HTTP) +- **Streamable HTTPS**: للخوادم البعيدة (اتصال مرن، ربما ثنائي الاتجاه عبر HTTPS، يستخدم غالباً SSE للتدفقات من الخادم إلى العميل) + +## فيديو تعليمي + +شاهد هذا الفيديو التعليمي للحصول على دليل شامل حول تكامل MCP مع CrewAI: + + + +## التثبيت + +يتطلب تكامل CrewAI MCP مكتبة `mcp`: + +```shell +# For Simple DSL Integration (Recommended) +uv add mcp + +# For Advanced MCPServerAdapter usage +uv pip install 'crewai-tools[mcp]' +``` + +## البدء السريع: تكامل DSL البسيط + +أسهل طريقة لدمج خوادم MCP هي استخدام حقل `mcps` على وكلائك. يمكنك استخدام مراجع نصية أو إعدادات منظمة. + +### البدء السريع مع المراجع النصية + +```python +from crewai import Agent, Task, Crew + +# Create agent with MCP tools using string references +research_agent = Agent( + role="Research Analyst", + goal="Find and analyze information using advanced search tools", + backstory="Expert researcher with access to multiple data sources", + mcps=[ + "https://mcp.exa.ai/mcp?api_key=your_key&profile=your_profile", + "snowflake#run_query" + ] +) + +# Create task +research_task = Task( + description="Research the latest developments in AI agent frameworks", + expected_output="Comprehensive research report with citations", + agent=research_agent +) + +# Create and run crew +crew = Crew(agents=[research_agent], tasks=[research_task]) +result = crew.kickoff() +``` + +### البدء السريع مع الإعدادات المنظمة + +```python +from crewai import Agent, Task, Crew +from crewai.mcp import MCPServerStdio, MCPServerHTTP, MCPServerSSE + +# Create agent with structured MCP configurations +research_agent = Agent( + role="Research Analyst", + goal="Find and analyze information using advanced search tools", + backstory="Expert researcher with access to multiple data sources", + mcps=[ + # Local stdio server + MCPServerStdio( + command="python", + args=["local_server.py"], + env={"API_KEY": "your_key"}, + ), + # Remote HTTP server + MCPServerHTTP( + url="https://api.research.com/mcp", + headers={"Authorization": "Bearer your_token"}, + ), + ] +) + +# Create task +research_task = Task( + description="Research the latest developments in AI agent frameworks", + expected_output="Comprehensive research report with citations", + agent=research_agent +) + +# Create and run crew +crew = Crew(agents=[research_agent], tasks=[research_task]) +result = crew.kickoff() +``` + +هذا كل شيء! يتم اكتشاف أدوات MCP تلقائياً وإتاحتها لوكيلك. + +## تنسيقات مراجع MCP + +يدعم حقل `mcps` كلاً من **المراجع النصية** (للإعداد السريع) و**الإعدادات المنظمة** (للتحكم الكامل). يمكنك مزج كلا التنسيقين في نفس القائمة. + +### المراجع النصية + +#### خوادم MCP الخارجية + +```python +mcps=[ + # Full server - get all available tools + "https://mcp.example.com/api", + + # Specific tool from server using # syntax + "https://api.weather.com/mcp#get_current_weather", + + # Server with authentication parameters + "https://mcp.exa.ai/mcp?api_key=your_key&profile=your_profile" +] +``` + +#### تكاملات MCP المتصلة + +اربط خوادم MCP من كتالوج CrewAI أو أحضر خوادمك الخاصة. بمجرد الاتصال في حسابك، أشر إليها بالمعرف المختصر: + +```python +mcps=[ + # Connected MCP - get all available tools + "snowflake", + + # Specific tool from a connected MCP using # syntax + "stripe#list_invoices", + + # Multiple connected MCPs + "snowflake", + "stripe", + "github" +] +``` + +### الإعدادات المنظمة + +#### نقل Stdio (خوادم محلية) + +مثالي لخوادم MCP المحلية التي تعمل كعمليات: + +```python +from crewai.mcp import MCPServerStdio +from crewai.mcp.filters import create_static_tool_filter + +mcps=[ + MCPServerStdio( + command="npx", + args=["-y", "@modelcontextprotocol/server-filesystem"], + env={"API_KEY": "your_key"}, + tool_filter=create_static_tool_filter( + allowed_tool_names=["read_file", "write_file"] + ), + cache_tools_list=True, + ), + # Python-based server + MCPServerStdio( + command="python", + args=["path/to/server.py"], + env={"UV_PYTHON": "3.12", "API_KEY": "your_key"}, + ), +] +``` + +#### نقل HTTP/Streamable HTTP (خوادم بعيدة) + +لخوادم MCP البعيدة عبر HTTP/HTTPS: + +```python +from crewai.mcp import MCPServerHTTP + +mcps=[ + # Streamable HTTP (default) + MCPServerHTTP( + url="https://api.example.com/mcp", + headers={"Authorization": "Bearer your_token"}, + streamable=True, + cache_tools_list=True, + ), + # Standard HTTP + MCPServerHTTP( + url="https://api.example.com/mcp", + headers={"Authorization": "Bearer your_token"}, + streamable=False, + ), +] +``` + +#### نقل SSE (البث في الوقت الفعلي) + +للخوادم البعيدة التي تستخدم Server-Sent Events: + +```python +from crewai.mcp import MCPServerSSE + +mcps=[ + MCPServerSSE( + url="https://stream.example.com/mcp/sse", + headers={"Authorization": "Bearer your_token"}, + cache_tools_list=True, + ), +] +``` + +### مراجع مختلطة + +يمكنك دمج المراجع النصية والإعدادات المنظمة: + +```python +from crewai.mcp import MCPServerStdio, MCPServerHTTP + +mcps=[ + # String references + "https://external-api.com/mcp", # External server + "snowflake", # Connected MCP from catalog + + # Structured configurations + MCPServerStdio( + command="npx", + args=["-y", "@modelcontextprotocol/server-filesystem"], + ), + MCPServerHTTP( + url="https://api.example.com/mcp", + headers={"Authorization": "Bearer token"}, + ), +] +``` + +### تصفية الأدوات + +تدعم الإعدادات المنظمة تصفية أدوات متقدمة: + +```python +from crewai.mcp import MCPServerStdio +from crewai.mcp.filters import create_static_tool_filter, create_dynamic_tool_filter, ToolFilterContext + +# Static filtering (allow/block lists) +static_filter = create_static_tool_filter( + allowed_tool_names=["read_file", "write_file"], + blocked_tool_names=["delete_file"], +) + +# Dynamic filtering (context-aware) +def dynamic_filter(context: ToolFilterContext, tool: dict) -> bool: + # Block dangerous tools for certain agent roles + if context.agent.role == "Code Reviewer": + if "delete" in tool.get("name", "").lower(): + return False + return True + +mcps=[ + MCPServerStdio( + command="npx", + args=["-y", "@modelcontextprotocol/server-filesystem"], + tool_filter=static_filter, # or dynamic_filter + ), +] +``` + +## معاملات الإعداد + +يدعم كل نوع نقل خيارات إعداد محددة: + +### معاملات MCPServerStdio + +- **`command`** (مطلوب): الأمر المراد تنفيذه (مثل `"python"` أو `"node"` أو `"npx"` أو `"uvx"`) +- **`args`** (اختياري): قائمة وسيطات الأمر (مثل `["server.py"]` أو `["-y", "@mcp/server"]`) +- **`env`** (اختياري): قاموس متغيرات البيئة لتمريرها إلى العملية +- **`tool_filter`** (اختياري): دالة تصفية الأدوات لتصفية الأدوات المتاحة +- **`cache_tools_list`** (اختياري): ما إذا كان يجب تخزين قائمة الأدوات مؤقتاً لوصول أسرع لاحقاً (الافتراضي: `False`) + +### معاملات MCPServerHTTP + +- **`url`** (مطلوب): عنوان URL الخادم (مثل `"https://api.example.com/mcp"`) +- **`headers`** (اختياري): قاموس رؤوس HTTP للمصادقة أو أغراض أخرى +- **`streamable`** (اختياري): ما إذا كان يجب استخدام نقل HTTP القابل للبث (الافتراضي: `True`) +- **`tool_filter`** (اختياري): دالة تصفية الأدوات لتصفية الأدوات المتاحة +- **`cache_tools_list`** (اختياري): ما إذا كان يجب تخزين قائمة الأدوات مؤقتاً (الافتراضي: `False`) + +### معاملات MCPServerSSE + +- **`url`** (مطلوب): عنوان URL الخادم (مثل `"https://api.example.com/mcp/sse"`) +- **`headers`** (اختياري): قاموس رؤوس HTTP للمصادقة أو أغراض أخرى +- **`tool_filter`** (اختياري): دالة تصفية الأدوات لتصفية الأدوات المتاحة +- **`cache_tools_list`** (اختياري): ما إذا كان يجب تخزين قائمة الأدوات مؤقتاً (الافتراضي: `False`) + +### المعاملات المشتركة + +تدعم جميع أنواع النقل: + +- **`tool_filter`**: دالة تصفية للتحكم في الأدوات المتاحة. يمكن أن تكون: + - `None` (الافتراضي): جميع الأدوات متاحة + - تصفية ثابتة: تُنشأ باستخدام `create_static_tool_filter()` لقوائم السماح/الحظر + - تصفية ديناميكية: تُنشأ باستخدام `create_dynamic_tool_filter()` للتصفية الواعية بالسياق +- **`cache_tools_list`**: عند `True`، تخزن قائمة الأدوات مؤقتاً بعد أول اكتشاف لتحسين الأداء في الاتصالات اللاحقة + +## الميزات الرئيسية + +- **اكتشاف تلقائي للأدوات**: يتم اكتشاف الأدوات ودمجها تلقائياً +- **منع تعارض الأسماء**: تُضاف بادئات أسماء الخوادم لأسماء الأدوات +- **محسّن للأداء**: اتصالات حسب الطلب مع تخزين مؤقت للمخططات +- **مرونة في الأخطاء**: تعامل أنيق مع الخوادم غير المتاحة +- **حماية المهلة الزمنية**: مهلات زمنية مدمجة تمنع تعليق الاتصالات +- **تكامل شفاف**: يعمل بسلاسة مع ميزات CrewAI الموجودة +- **دعم نقل كامل**: أنواع نقل Stdio وHTTP/Streamable HTTP وSSE +- **تصفية متقدمة**: قدرات تصفية أدوات ثابتة وديناميكية +- **مصادقة مرنة**: دعم للرؤوس ومتغيرات البيئة ومعاملات الاستعلام + +## معالجة الأخطاء + +صُمم تكامل MCP DSL ليكون مرناً ويتعامل مع الفشل بأناقة: + +```python +from crewai import Agent +from crewai.mcp import MCPServerStdio, MCPServerHTTP + +agent = Agent( + role="Resilient Agent", + goal="Continue working despite server issues", + backstory="Agent that handles failures gracefully", + mcps=[ + # String references + "https://reliable-server.com/mcp", # Will work + "https://unreachable-server.com/mcp", # Will be skipped gracefully + "snowflake", # Connected MCP from catalog + + # Structured configs + MCPServerStdio( + command="python", + args=["reliable_server.py"], # Will work + ), + MCPServerHTTP( + url="https://slow-server.com/mcp", # Will timeout gracefully + ), + ] +) +# Agent will use tools from working servers and log warnings for failing ones +``` + +جميع أخطاء الاتصال تُعالج بأناقة: + +- **فشل الاتصال**: تُسجل كتحذيرات، ويستمر الوكيل مع الأدوات المتاحة +- **أخطاء المهلة الزمنية**: تنتهي الاتصالات بعد 30 ثانية (قابلة للتعديل) +- **أخطاء المصادقة**: تُسجل بوضوح للتصحيح +- **إعدادات غير صالحة**: تُرفع أخطاء التحقق عند إنشاء الوكيل + +## متقدم: MCPServerAdapter + +للسيناريوهات المعقدة التي تتطلب إدارة اتصال يدوية، استخدم فئة `MCPServerAdapter` من `crewai-tools`. استخدام مدير سياق Python (تعليمة `with`) هو النهج الموصى به لأنه يتعامل تلقائياً مع بدء وإيقاف الاتصال بخادم MCP. + +## إعداد الاتصال + +يدعم `MCPServerAdapter` عدة خيارات إعداد لتخصيص سلوك الاتصال: + +- **`connect_timeout`** (اختياري): الحد الأقصى للوقت بالثواني لانتظار إنشاء اتصال بخادم MCP. القيمة الافتراضية 30 ثانية إذا لم تُحدد. هذا مفيد بشكل خاص للخوادم البعيدة التي قد يكون لها أوقات استجابة متغيرة. + +```python +# Example with custom connection timeout +with MCPServerAdapter(server_params, connect_timeout=60) as tools: + # Connection will timeout after 60 seconds if not established + pass +``` + +```python +from crewai import Agent +from crewai_tools import MCPServerAdapter +from mcp import StdioServerParameters # For Stdio Server + +# Example server_params (choose one based on your server type): +# 1. Stdio Server: +server_params=StdioServerParameters( + command="python3", + args=["servers/your_server.py"], + env={"UV_PYTHON": "3.12", **os.environ}, +) + +# 2. SSE Server: +server_params = { + "url": "http://localhost:8000/sse", + "transport": "sse" +} + +# 3. Streamable HTTP Server: +server_params = { + "url": "http://localhost:8001/mcp", + "transport": "streamable-http" +} + +# Example usage (uncomment and adapt once server_params is set): +with MCPServerAdapter(server_params, connect_timeout=60) as mcp_tools: + print(f"Available tools: {[tool.name for tool in mcp_tools]}") + + my_agent = Agent( + role="MCP Tool User", + goal="Utilize tools from an MCP server.", + backstory="I can connect to MCP servers and use their tools.", + tools=mcp_tools, # Pass the loaded tools to your agent + reasoning=True, + verbose=True + ) + # ... rest of your crew setup ... +``` + +يوضح هذا النمط العام كيفية دمج الأدوات. للحصول على أمثلة محددة مصممة لكل نوع نقل، راجع الأدلة التفصيلية أدناه. + +## تصفية الأدوات + +هناك طريقتان لتصفية الأدوات: + +1. الوصول إلى أداة محددة باستخدام فهرسة نمط القاموس. +2. تمرير قائمة أسماء الأدوات إلى منشئ `MCPServerAdapter`. + +### الوصول إلى أداة محددة باستخدام فهرسة نمط القاموس. + +```python +with MCPServerAdapter(server_params, connect_timeout=60) as mcp_tools: + print(f"Available tools: {[tool.name for tool in mcp_tools]}") + + my_agent = Agent( + role="MCP Tool User", + goal="Utilize tools from an MCP server.", + backstory="I can connect to MCP servers and use their tools.", + tools=[mcp_tools["tool_name"]], # Pass the loaded tools to your agent + reasoning=True, + verbose=True + ) + # ... rest of your crew setup ... +``` + +### تمرير قائمة أسماء الأدوات إلى منشئ `MCPServerAdapter`. + +```python +with MCPServerAdapter(server_params, "tool_name", connect_timeout=60) as mcp_tools: + print(f"Available tools: {[tool.name for tool in mcp_tools]}") + + my_agent = Agent( + role="MCP Tool User", + goal="Utilize tools from an MCP server.", + backstory="I can connect to MCP servers and use their tools.", + tools=mcp_tools, # Pass the loaded tools to your agent + reasoning=True, + verbose=True + ) + # ... rest of your crew setup ... +``` + +## الاستخدام مع CrewBase + +لاستخدام أدوات MCPServer ضمن فئة CrewBase، استخدم طريقة `get_mcp_tools`. يجب توفير إعدادات الخادم عبر خاصية `mcp_server_params`. يمكنك تمرير إعداد واحد أو قائمة من إعدادات خوادم متعددة. + +```python +@CrewBase +class CrewWithMCP: + # ... define your agents and tasks config file ... + + mcp_server_params = [ + # Streamable HTTP Server + { + "url": "http://localhost:8001/mcp", + "transport": "streamable-http" + }, + # SSE Server + { + "url": "http://localhost:8000/sse", + "transport": "sse" + }, + # StdIO Server + StdioServerParameters( + command="python3", + args=["servers/your_stdio_server.py"], + env={"UV_PYTHON": "3.12", **os.environ}, + ) + ] + + @agent + def your_agent(self): + return Agent(config=self.agents_config["your_agent"], tools=self.get_mcp_tools()) # get all available tools + + # ... rest of your crew setup ... +``` + + +عندما تكون فئة الطاقم مزينة بـ `@CrewBase`، تُدار دورة حياة المحول نيابة عنك: + +- أول استدعاء لـ `get_mcp_tools()` ينشئ بكسل `MCPServerAdapter` مشتركاً يُعاد استخدامه من قبل كل وكيل في الطاقم. +- يُغلق المحول تلقائياً بعد اكتمال `.kickoff()` بفضل خطاف ما بعد التشغيل الضمني المحقون من `@CrewBase`، لذا لا حاجة للتنظيف اليدوي. +- إذا لم يتم تعريف `mcp_server_params`، يُرجع `get_mcp_tools()` ببساطة قائمة فارغة، مما يسمح لنفس مسارات الكود بالعمل مع أو بدون إعداد MCP. + +هذا يجعل من الآمن استدعاء `get_mcp_tools()` من طرق وكلاء متعددة أو تفعيل MCP بشكل انتقائي لكل بيئة. + + +### إعداد مهلة الاتصال + +يمكنك إعداد مهلة الاتصال لخوادم MCP عن طريق تعيين خاصية فئة `mcp_connect_timeout`. إذا لم تُحدد مهلة، تكون القيمة الافتراضية 30 ثانية. + +```python +@CrewBase +class CrewWithMCP: + mcp_server_params = [...] + mcp_connect_timeout = 60 # 60 seconds timeout for all MCP connections + + @agent + def your_agent(self): + return Agent(config=self.agents_config["your_agent"], tools=self.get_mcp_tools()) +``` + +### تصفية الأدوات + +يمكنك تصفية الأدوات المتاحة لوكيلك عن طريق تمرير قائمة أسماء الأدوات إلى طريقة `get_mcp_tools`. + +```python +@agent +def another_agent(self): + return Agent( + config=self.agents_config["your_agent"], + tools=self.get_mcp_tools("tool_1", "tool_2") # get specific tools + ) +``` + +## استكشاف تكاملات MCP + + + + **الموصى به**: استخدم صياغة حقل `mcps=[]` البسيطة لتكامل MCP بلا جهد. + + + الاتصال بخوادم MCP المحلية عبر الإدخال/الإخراج القياسي. مثالي للنصوص البرمجية والملفات التنفيذية المحلية. + + + التكامل مع خوادم MCP البعيدة باستخدام Server-Sent Events لبث البيانات في الوقت الفعلي. + + + استخدام Streamable HTTP المرن للاتصال القوي مع خوادم MCP البعيدة. + + + تجميع الأدوات من عدة خوادم MCP بشكل متزامن باستخدام محول واحد. + + + مراجعة أفضل ممارسات الأمان المهمة لتكامل MCP للحفاظ على سلامة وكلائك. + + + +تحقق من هذا المستودع للحصول على عروض وأمثلة كاملة لتكامل MCP مع CrewAI! + + + CrewAI MCP Demo + + +## البقاء آمناً مع MCP + +تأكد دائماً من أنك تثق بخادم MCP قبل استخدامه. + +#### تحذير أمني: هجمات إعادة ربط DNS + +يمكن أن تكون عمليات نقل SSE عرضة لهجمات إعادة ربط DNS إذا لم تكن مؤمنة بشكل صحيح. +لمنع ذلك: + +1. **تحقق دائماً من رؤوس Origin** على اتصالات SSE الواردة للتأكد من أنها تأتي من مصادر متوقعة +2. **تجنب ربط الخوادم بجميع واجهات الشبكة** (0.0.0.0) عند التشغيل محلياً - اربط فقط بـ localhost (127.0.0.1) بدلاً من ذلك +3. **نفّذ مصادقة مناسبة** لجميع اتصالات SSE + +بدون هذه الحمايات، يمكن للمهاجمين استخدام إعادة ربط DNS للتفاعل مع خوادم MCP المحلية من مواقع ويب بعيدة. + +لمزيد من التفاصيل، راجع [وثائق أمان نقل MCP من Anthropic](https://modelcontextprotocol.io/docs/concepts/transports#security-considerations). + +### القيود + +- **الأوليات المدعومة**: حالياً، يدعم `MCPServerAdapter` بشكل أساسي تكييف `أدوات` MCP. + لا يتم دمج أوليات MCP الأخرى مثل `prompts` أو `resources` مباشرة كمكونات CrewAI من خلال هذا المحول في هذا الوقت. +- **معالجة المخرجات**: يعالج المحول عادةً المخرجات النصية الرئيسية من أداة MCP (مثل `.content[0].text`). قد تتطلب المخرجات المعقدة أو متعددة الوسائط معالجة مخصصة إذا لم تتناسب مع هذا النمط. diff --git a/docs/ar/mcp/security.mdx b/docs/ar/mcp/security.mdx new file mode 100644 index 000000000..e968ff9f5 --- /dev/null +++ b/docs/ar/mcp/security.mdx @@ -0,0 +1,149 @@ +--- +title: اعتبارات أمان MCP +description: تعرف على أفضل ممارسات الأمان المهمة عند دمج خوادم MCP مع وكلاء CrewAI. +icon: lock +mode: "wide" +--- + +## نظرة عامة + + +الجانب الأكثر أهمية في أمان MCP هو **الثقة**. يجب أن تتصل فقط بخوادم MCP التي تثق بها **بالكامل**. + + +عند دمج خدمات خارجية مثل خوادم MCP (بروتوكول سياق النموذج) في وكلاء CrewAI، يكون الأمان أمراً بالغ الأهمية. +يمكن لخوادم MCP تنفيذ التعليمات البرمجية والوصول إلى البيانات أو التفاعل مع أنظمة أخرى بناءً على الأدوات التي تكشفها. +من الضروري فهم الآثار واتباع أفضل الممارسات لحماية تطبيقاتك وبياناتك. + +### المخاطر + +- تنفيذ تعليمات برمجية عشوائية على الجهاز الذي يعمل عليه الوكيل (خاصة مع نقل `Stdio` إذا كان الخادم يمكنه التحكم في الأمر المُنفذ). +- كشف بيانات حساسة من وكيلك أو بيئته. +- التلاعب بسلوك وكيلك بطرق غير مقصودة، بما في ذلك إجراء استدعاءات API غير مصرح بها نيابة عنك. +- اختطاف عملية استدلال وكيلك من خلال تقنيات حقن المطالبات المتطورة (انظر أدناه). + +### 1. الثقة بخوادم MCP + + +**اتصل فقط بخوادم MCP التي تثق بها.** + + +قبل إعداد `MCPServerAdapter` للاتصال بخادم MCP، تأكد من معرفة: +- **من يشغل الخادم؟** هل هو خدمة معروفة وذات سمعة جيدة، أم خادم داخلي تحت سيطرتك؟ +- **ما الأدوات التي يكشفها؟** افهم قدرات الأدوات. هل يمكن إساءة استخدامها إذا سيطر مهاجم أو إذا كان الخادم نفسه خبيثاً؟ +- **ما البيانات التي يصل إليها أو يعالجها؟** كن على دراية بأي معلومات حساسة قد تُرسل إلى خادم MCP أو يتعامل معها. + +تجنب الاتصال بخوادم MCP غير معروفة أو غير موثقة، خاصة إذا كان وكلاؤك يتعاملون مع مهام أو بيانات حساسة. + +### 2. حقن المطالبات الآمن عبر بيانات الأداة الوصفية: خطر "بروتوكول التحكم بالنموذج" + +خطر كبير وخفي هو إمكانية حقن المطالبات عبر البيانات الوصفية للأداة. إليك كيف يعمل: + +1. عندما يتصل وكيل CrewAI بخادم MCP، يطلب عادةً قائمة الأدوات المتاحة. +2. يستجيب خادم MCP ببيانات وصفية لكل أداة، بما في ذلك اسمها ووصفها وأوصاف معاملاتها. +3. يستخدم نموذج اللغة (LLM) الأساسي لوكيلك هذه البيانات الوصفية لفهم كيف ومتى يستخدم الأدوات. +4. يمكن لخادم MCP خبيث صياغة بياناته الوصفية للأدوات لتتضمن تعليمات مخفية أو صريحة تعمل كحقن مطالبات. + +**الأهم، يمكن أن يحدث هذا الهجوم بمجرد الاتصال بخادم خبيث وسرد أدواته، حتى لو لم يقرر وكيلك *استخدام* أي من تلك الأدوات.** مجرد التعرض للبيانات الوصفية الخبيثة يمكن أن يكون كافياً لاختراق سلوك الوكيل. + +**التخفيف:** + +* **الحذر الشديد مع الخوادم غير الموثوقة:** نكرر: *لا تتصل بخوادم MCP لا تثق بها بالكامل.* يجعل خطر حقن البيانات الوصفية هذا أمراً بالغ الأهمية. + +### أمان نقل Stdio + +عادةً ما يُستخدم نقل Stdio (الإدخال/الإخراج القياسي) لخوادم MCP المحلية التي تعمل على نفس الجهاز مثل تطبيق CrewAI. + +- **عزل العملية**: على الرغم من أنه أكثر أماناً بشكل عام لأنه لا يتضمن تعرض شبكي افتراضياً، تأكد من أن النص البرمجي أو الأمر الذي يُشغله `StdioServerParameters` من مصدر موثوق ولديه أذونات نظام ملفات مناسبة. +- **تنقية المدخلات**: إذا كان نص Stdio البرمجي يأخذ مدخلات معقدة مشتقة من تفاعلات الوكيل، تأكد من أن النص ينقي هذه المدخلات لمنع حقن الأوامر أو الثغرات الأخرى. +- **حدود الموارد**: كن على دراية بأن عملية خادم Stdio المحلية تستهلك موارد محلية (CPU، الذاكرة). تأكد من أنها تعمل بشكل جيد ولن تستنفد موارد النظام. + +### هجمات الوكيل المرتبك + +[مشكلة الوكيل المرتبك](https://en.wikipedia.org/wiki/Confused_deputy_problem) هي ثغرة أمنية كلاسيكية يمكن أن تظهر في تكاملات MCP، خاصة عندما يعمل خادم MCP كوسيط لخدمات طرف ثالث (مثل Google Calendar وGitHub) التي تستخدم OAuth 2.0 للترخيص. + +**السيناريو:** + +1. خادم MCP (نسميه `MCP-Proxy`) يسمح لوكيلك بالتفاعل مع `ThirdPartyAPI`. +2. يستخدم `MCP-Proxy` `client_id` ثابتاً واحداً خاصاً به عند التحدث مع خادم ترخيص `ThirdPartyAPI`. +3. أنت، كمستخدم، تصرح بشكل شرعي لـ `MCP-Proxy` بالوصول إلى `ThirdPartyAPI` نيابة عنك. +4. يصنع مهاجم رابطاً خبيثاً يبدأ تدفق OAuth مع `MCP-Proxy`، لكنه مصمم لخداع خادم ترخيص `ThirdPartyAPI`. +5. إذا نقرت على هذا الرابط، وشاهد خادم ترخيص `ThirdPartyAPI` ملف تعريف ارتباط الموافقة الموجود لـ `client_id` الخاص بـ `MCP-Proxy`، فقد *يتخطى* طلب موافقتك مرة أخرى. +6. قد يُخدع `MCP-Proxy` بعد ذلك لتمرير رمز ترخيص إلى المهاجم. + +**التخفيف (بشكل أساسي لمطوري خوادم MCP):** + +* يجب على خوادم MCP الوسيطة التي تستخدم معرفات عميل ثابتة للخدمات النهائية الحصول على **موافقة صريحة من المستخدم** لكل تطبيق عميل أو وكيل يتصل بها قبل بدء تدفق OAuth. + +**تداعيات مستخدم CrewAI:** + +* كن حذراً إذا أعاد خادم MCP توجيهك لمصادقات OAuth متعددة، خاصة إذا بدت غير متوقعة أو كانت الأذونات المطلوبة واسعة جداً. + +### أمان النقل البعيد (SSE و Streamable HTTP) + +عند الاتصال بخوادم MCP البعيدة عبر SSE أو Streamable HTTP، فإن ممارسات أمان الويب القياسية ضرورية. + +### اعتبارات أمان SSE + +### أ. هجمات إعادة ربط DNS (خاصة لـ SSE) + + +**احمِ ضد هجمات إعادة ربط DNS.** + + +تسمح إعادة ربط DNS لموقع ويب يتحكم فيه مهاجم بتجاوز سياسة نفس الأصل وإجراء طلبات لخوادم على شبكة المستخدم المحلية. + +**استراتيجيات التخفيف لمنفذي خوادم MCP:** +- **تحقق من رؤوس `Origin` و `Host`**: يجب على خوادم MCP (خاصة SSE) التحقق من رؤوس HTTP لضمان أن الطلبات تأتي من نطاقات/عملاء متوقعين. +- **اربط بـ `localhost` (127.0.0.1)**: عند تشغيل خوادم MCP محلياً للتطوير، اربطها بـ `127.0.0.1` بدلاً من `0.0.0.0`. +- **المصادقة**: اطلب مصادقة لجميع الاتصالات بخادم MCP. + +### ب. استخدم HTTPS + +- **تشفير البيانات أثناء النقل**: استخدم دائماً HTTPS لعناوين URL خوادم MCP البعيدة لتشفير الاتصال. + +### ج. تمرير الرمز (نمط مضاد) + +هذا يتعلق بشكل أساسي بمطوري خوادم MCP لكن فهمه يساعد في اختيار خوادم آمنة. + +"تمرير الرمز" هو عندما يقبل خادم MCP رمز وصول من وكيل CrewAI ويمرره ببساطة إلى API آخر بدون تحقق مناسب. + +**المخاطر:** +* يتجاوز ضوابط الأمان على خادم MCP أو API النهائي. +* يكسر مسارات التدقيق والمساءلة. +* يسمح بإساءة استخدام الرموز المسروقة. + +### د. التحقق من المدخلات وتنقيتها + +- **التحقق من المدخلات أمر بالغ الأهمية**: يجب على خوادم MCP التحقق بصرامة من جميع المدخلات المستلمة من الوكلاء *قبل* معالجتها أو تمريرها إلى الأدوات. هذا دفاع أساسي ضد العديد من الثغرات الشائعة: + - **حقن الأوامر:** إذا كانت أداة تبني أوامر shell أو استعلامات SQL بناءً على المدخلات، يجب على الخادم تنقية هذه المدخلات بدقة. + - **اجتياز المسار:** إذا وصلت أداة إلى ملفات بناءً على معاملات المدخلات، يجب على الخادم التحقق من هذه المسارات وتنقيتها. + - **فحوصات نوع البيانات والنطاق:** يجب أن تضمن الخوادم توافق البيانات مع الأنواع والنطاقات المتوقعة. + +### هـ. تحديد المعدل وإدارة الموارد + +- **منع الإساءة**: يجب أن تنفذ خوادم MCP تحديد المعدل لمنع الإساءة. +- **إعادة المحاولة من جانب العميل**: نفّذ منطق إعادة محاولة معقول في مهام CrewAI. + +## 4. نصائح لتنفيذ خادم MCP آمن (للمطورين) + +إذا كنت تطور خادم MCP قد تتصل به وكلاء CrewAI، ضع في الاعتبار أفضل الممارسات التالية: + +- **اتبع ممارسات البرمجة الآمنة**: التزم بمبادئ البرمجة الآمنة القياسية (مثل OWASP Top 10). +- **مبدأ الحد الأدنى من الصلاحيات**: تأكد من أن العملية التي تشغل خادم MCP لديها فقط الأذونات اللازمة. +- **إدارة الاعتماديات**: حافظ على تحديث جميع الاعتماديات لتصحيح الثغرات المعروفة. +- **الإعدادات الافتراضية الآمنة**: صمم خادمك وأدواته لتكون آمنة افتراضياً. +- **التحكم في الوصول للأدوات**: نفّذ آليات قوية للتحكم في الوكلاء أو المستخدمين المصرح لهم بالوصول إلى أدوات محددة. +- **معالجة أخطاء آمنة**: يجب ألا تكشف الخوادم رسائل خطأ داخلية مفصلة أو تتبعات المكدس للعميل. +- **التسجيل والمراقبة الشاملة**: نفّذ تسجيلاً مفصلاً للأحداث المتعلقة بالأمان. +- **الالتزام بمواصفات ترخيص MCP**: إذا كنت تنفذ المصادقة والترخيص، اتبع بدقة [مواصفات ترخيص MCP](https://modelcontextprotocol.io/specification/draft/basic/authorization). +- **تدقيقات أمنية منتظمة**: إذا كان خادم MCP يتعامل مع بيانات حساسة، فكر في إجراء تدقيقات أمنية دورية. + +## 5. قراءة إضافية + +لمزيد من المعلومات التفصيلية حول أمان MCP، راجع التوثيق الرسمي: +- **[أمان نقل MCP](https://modelcontextprotocol.io/docs/concepts/transports#security-considerations)** + +من خلال فهم اعتبارات الأمان هذه وتنفيذ أفضل الممارسات، يمكنك الاستفادة بأمان من قوة خوادم MCP في مشاريع CrewAI. +هذه ليست شاملة بأي حال، لكنها تغطي المخاوف الأمنية الأكثر شيوعاً وأهمية. +ستستمر التهديدات في التطور، لذا من المهم البقاء على اطلاع وتكييف إجراءات الأمان وفقاً لذلك. diff --git a/docs/ar/mcp/sse.mdx b/docs/ar/mcp/sse.mdx new file mode 100644 index 000000000..3e5e35246 --- /dev/null +++ b/docs/ar/mcp/sse.mdx @@ -0,0 +1,151 @@ +--- +title: نقل SSE +description: تعلم كيفية ربط CrewAI بخوادم MCP البعيدة باستخدام Server-Sent Events (SSE) للاتصال في الوقت الفعلي. +icon: wifi +mode: "wide" +--- + +## نظرة عامة + +توفر Server-Sent Events (SSE) طريقة قياسية لخادم الويب لإرسال تحديثات إلى العميل عبر اتصال HTTP واحد طويل الأمد. في سياق MCP، تُستخدم SSE للخوادم البعيدة لبث البيانات (مثل استجابات الأدوات) إلى تطبيق CrewAI في الوقت الفعلي. + +## المفاهيم الرئيسية + +- **خوادم بعيدة**: SSE مناسب لخوادم MCP المستضافة عن بُعد. +- **بث أحادي الاتجاه**: عادةً ما يكون SSE قناة اتصال أحادية الاتجاه من الخادم إلى العميل. +- **إعداد `MCPServerAdapter`**: لـ SSE، ستوفر عنوان URL الخادم وتحدد نوع النقل. + +## الاتصال عبر SSE + +يمكنك الاتصال بخادم MCP المبني على SSE باستخدام نهجين رئيسيين لإدارة دورة حياة الاتصال: + +### 1. اتصال مُدار بالكامل (الموصى به) + +استخدام مدير سياق Python (تعليمة `with`) هو النهج الموصى به. يتعامل تلقائياً مع إنشاء وإغلاق الاتصال بخادم MCP SSE. + +```python +from crewai import Agent, Task, Crew, Process +from crewai_tools import MCPServerAdapter + +server_params = { + "url": "http://localhost:8000/sse", # Replace with your actual SSE server URL + "transport": "sse" +} + +# Using MCPServerAdapter with a context manager +try: + with MCPServerAdapter(server_params) as tools: + print(f"Available tools from SSE MCP server: {[tool.name for tool in tools]}") + + # Example: Using a tool from the SSE MCP server + sse_agent = Agent( + role="Remote Service User", + goal="Utilize a tool provided by a remote SSE MCP server.", + backstory="An AI agent that connects to external services via SSE.", + tools=tools, + reasoning=True, + verbose=True, + ) + + sse_task = Task( + description="Fetch real-time stock updates for 'AAPL' using an SSE tool.", + expected_output="The latest stock price for AAPL.", + agent=sse_agent, + markdown=True + ) + + sse_crew = Crew( + agents=[sse_agent], + tasks=[sse_task], + verbose=True, + process=Process.sequential + ) + + if tools: # Only kickoff if tools were loaded + result = sse_crew.kickoff() # Add inputs={'stock_symbol': 'AAPL'} if tool requires it + print("\nCrew Task Result (SSE - Managed):\n", result) + else: + print("Skipping crew kickoff as tools were not loaded (check server connection).") + +except Exception as e: + print(f"Error connecting to or using SSE MCP server (Managed): {e}") + print("Ensure the SSE MCP server is running and accessible at the specified URL.") + +``` + + +استبدل `"http://localhost:8000/sse"` بعنوان URL الفعلي لخادم MCP SSE الخاص بك. + + +### 2. دورة حياة اتصال يدوية + +إذا كنت بحاجة إلى تحكم أدق، يمكنك إدارة دورة حياة اتصال `MCPServerAdapter` يدوياً. + + +**يجب** عليك استدعاء `mcp_server_adapter.stop()` لضمان إغلاق الاتصال وتحرير الموارد. يُوصى بشدة باستخدام كتلة `try...finally`. + + +```python +from crewai import Agent, Task, Crew, Process +from crewai_tools import MCPServerAdapter + +server_params = { + "url": "http://localhost:8000/sse", # Replace with your actual SSE server URL + "transport": "sse" +} + +mcp_server_adapter = None +try: + mcp_server_adapter = MCPServerAdapter(server_params) + mcp_server_adapter.start() + tools = mcp_server_adapter.tools + print(f"Available tools (manual SSE): {[tool.name for tool in tools]}") + + manual_sse_agent = Agent( + role="Remote Data Analyst", + goal="Analyze data fetched from a remote SSE MCP server using manual connection management.", + backstory="An AI skilled in handling SSE connections explicitly.", + tools=tools, + verbose=True + ) + + analysis_task = Task( + description="Fetch and analyze the latest user activity trends from the SSE server.", + expected_output="A summary report of user activity trends.", + agent=manual_sse_agent + ) + + analysis_crew = Crew( + agents=[manual_sse_agent], + tasks=[analysis_task], + verbose=True, + process=Process.sequential + ) + + result = analysis_crew.kickoff() + print("\nCrew Task Result (SSE - Manual):\n", result) + +except Exception as e: + print(f"An error occurred during manual SSE MCP integration: {e}") + print("Ensure the SSE MCP server is running and accessible.") +finally: + if mcp_server_adapter and mcp_server_adapter.is_connected: + print("Stopping SSE MCP server connection (manual)...") + mcp_server_adapter.stop() # **Crucial: Ensure stop is called** + elif mcp_server_adapter: + print("SSE MCP server adapter was not connected. No stop needed or start failed.") + +``` + +## اعتبارات أمان SSE + + +**هجمات إعادة ربط DNS**: يمكن أن تكون عمليات نقل SSE عرضة لهجمات إعادة ربط DNS إذا لم يكن خادم MCP مؤمناً بشكل صحيح. قد يسمح هذا لمواقع ويب خبيثة بالتفاعل مع خوادم MCP المحلية أو على الشبكة الداخلية. + + +للتخفيف من هذا الخطر: +- يجب أن تتحقق تطبيقات خادم MCP من **رؤوس `Origin`** على اتصالات SSE الواردة. +- عند تشغيل خوادم MCP SSE محلية للتطوير، **اربط فقط بـ `localhost` (`127.0.0.1`)** بدلاً من جميع واجهات الشبكة (`0.0.0.0`). +- نفّذ **مصادقة مناسبة** لجميع اتصالات SSE إذا كشفت أدوات أو بيانات حساسة. + +للحصول على نظرة شاملة على أفضل ممارسات الأمان، يرجى الرجوع إلى صفحة [اعتبارات الأمان](./security.mdx) ووثائق [أمان نقل MCP](https://modelcontextprotocol.io/docs/concepts/transports#security-considerations) الرسمية. diff --git a/docs/ar/mcp/stdio.mdx b/docs/ar/mcp/stdio.mdx new file mode 100644 index 000000000..cf1b20e49 --- /dev/null +++ b/docs/ar/mcp/stdio.mdx @@ -0,0 +1,134 @@ +--- +title: نقل Stdio +description: تعلم كيفية ربط CrewAI بخوادم MCP المحلية باستخدام آلية نقل Stdio (الإدخال/الإخراج القياسي). +icon: server +mode: "wide" +--- + +## نظرة عامة + +صُمم نقل Stdio (الإدخال/الإخراج القياسي) لربط `MCPServerAdapter` بخوادم MCP المحلية التي تتواصل عبر تدفقات الإدخال والإخراج القياسية. يُستخدم هذا عادةً عندما يكون خادم MCP نصاً برمجياً أو ملفاً تنفيذياً يعمل على نفس الجهاز مثل تطبيق CrewAI. + +## المفاهيم الرئيسية + +- **التنفيذ المحلي**: يدير نقل Stdio عملية تعمل محلياً لخادم MCP. +- **`StdioServerParameters`**: تُستخدم هذه الفئة من مكتبة `mcp` لإعداد الأمر والوسيطات ومتغيرات البيئة لتشغيل خادم Stdio. + +## الاتصال عبر Stdio + +يمكنك الاتصال بخادم MCP المبني على Stdio باستخدام نهجين رئيسيين لإدارة دورة حياة الاتصال: + +### 1. اتصال مُدار بالكامل (الموصى به) + +استخدام مدير سياق Python (تعليمة `with`) هو النهج الموصى به. يتعامل تلقائياً مع بدء عملية خادم MCP وإيقافها عند الخروج من السياق. + +```python +from crewai import Agent, Task, Crew, Process +from crewai_tools import MCPServerAdapter +from mcp import StdioServerParameters +import os + +# Create a StdioServerParameters object +server_params=StdioServerParameters( + command="python3", + args=["servers/your_stdio_server.py"], + env={"UV_PYTHON": "3.12", **os.environ}, +) + +with MCPServerAdapter(server_params) as tools: + print(f"Available tools from Stdio MCP server: {[tool.name for tool in tools]}") + + # Example: Using the tools from the Stdio MCP server in a CrewAI Agent + research_agent = Agent( + role="Local Data Processor", + goal="Process data using a local Stdio-based tool.", + backstory="An AI that leverages local scripts via MCP for specialized tasks.", + tools=tools, + reasoning=True, + verbose=True, + ) + + processing_task = Task( + description="Process the input data file 'data.txt' and summarize its contents.", + expected_output="A summary of the processed data.", + agent=research_agent, + markdown=True + ) + + data_crew = Crew( + agents=[research_agent], + tasks=[processing_task], + verbose=True, + process=Process.sequential + ) + + result = data_crew.kickoff() + print("\nCrew Task Result (Stdio - Managed):\n", result) + +``` + +### 2. دورة حياة اتصال يدوية + +إذا كنت بحاجة إلى تحكم أدق في وقت بدء وإيقاف عملية خادم MCP Stdio، يمكنك إدارة دورة حياة `MCPServerAdapter` يدوياً. + + +**يجب** عليك استدعاء `mcp_server_adapter.stop()` لضمان إنهاء عملية الخادم وتحرير الموارد. يُوصى بشدة باستخدام كتلة `try...finally`. + + +```python +from crewai import Agent, Task, Crew, Process +from crewai_tools import MCPServerAdapter +from mcp import StdioServerParameters +import os + +# Create a StdioServerParameters object +stdio_params=StdioServerParameters( + command="python3", + args=["servers/your_stdio_server.py"], + env={"UV_PYTHON": "3.12", **os.environ}, +) + +mcp_server_adapter = MCPServerAdapter(server_params=stdio_params) +try: + mcp_server_adapter.start() # Manually start the connection and server process + tools = mcp_server_adapter.tools + print(f"Available tools (manual Stdio): {[tool.name for tool in tools]}") + + # Example: Using the tools with your Agent, Task, Crew setup + manual_agent = Agent( + role="Local Task Executor", + goal="Execute a specific local task using a manually managed Stdio tool.", + backstory="An AI proficient in controlling local processes via MCP.", + tools=tools, + verbose=True + ) + + manual_task = Task( + description="Execute the 'perform_analysis' command via the Stdio tool.", + expected_output="Results of the analysis.", + agent=manual_agent + ) + + manual_crew = Crew( + agents=[manual_agent], + tasks=[manual_task], + verbose=True, + process=Process.sequential + ) + + + result = manual_crew.kickoff() # Actual inputs depend on your tool + print("\nCrew Task Result (Stdio - Manual):\n", result) + +except Exception as e: + print(f"An error occurred during manual Stdio MCP integration: {e}") +finally: + if mcp_server_adapter and mcp_server_adapter.is_connected: # Check if connected before stopping + print("Stopping Stdio MCP server connection (manual)...") + mcp_server_adapter.stop() # **Crucial: Ensure stop is called** + elif mcp_server_adapter: # If adapter exists but not connected (e.g. start failed) + print("Stdio MCP server adapter was not connected. No stop needed or start failed.") + +``` + +تذكر استبدال المسارات والأوامر النائبة بتفاصيل خادم Stdio الفعلية. يمكن استخدام معامل `env` في `StdioServerParameters` لتعيين متغيرات البيئة لعملية الخادم، وهو مفيد لإعداد سلوكها أو توفير المسارات اللازمة (مثل `PYTHONPATH`). diff --git a/docs/ar/mcp/streamable-http.mdx b/docs/ar/mcp/streamable-http.mdx new file mode 100644 index 000000000..a4567ea74 --- /dev/null +++ b/docs/ar/mcp/streamable-http.mdx @@ -0,0 +1,136 @@ +--- +title: نقل Streamable HTTP +description: تعلم كيفية ربط CrewAI بخوادم MCP البعيدة باستخدام نقل Streamable HTTP المرن. +icon: globe +mode: "wide" +--- + +## نظرة عامة + +يوفر نقل Streamable HTTP طريقة مرنة للاتصال بخوادم MCP البعيدة. يُبنى عادةً على HTTP ويمكنه دعم أنماط اتصال متنوعة، بما في ذلك الطلب والاستجابة والبث، وأحياناً يستخدم Server-Sent Events (SSE) لتدفقات من الخادم إلى العميل ضمن تفاعل HTTP أوسع. + +## المفاهيم الرئيسية + +- **خوادم بعيدة**: مصمم لخوادم MCP المستضافة عن بُعد. +- **المرونة**: يمكنه دعم أنماط تفاعل أكثر تعقيداً من SSE العادي، بما في ذلك الاتصال ثنائي الاتجاه المحتمل إذا نفذه الخادم. +- **إعداد `MCPServerAdapter`**: ستحتاج إلى توفير عنوان URL الأساسي للخادم للاتصال MCP وتحديد `"streamable-http"` كنوع النقل. + +## الاتصال عبر Streamable HTTP + +لديك طريقتان رئيسيتان لإدارة دورة حياة الاتصال مع خادم MCP Streamable HTTP: + +### 1. اتصال مُدار بالكامل (الموصى به) + +النهج الموصى به هو استخدام مدير سياق Python (تعليمة `with`)، الذي يتعامل مع إعداد الاتصال وإنهائه تلقائياً. + +```python +from crewai import Agent, Task, Crew, Process +from crewai_tools import MCPServerAdapter + +server_params = { + "url": "http://localhost:8001/mcp", # Replace with your actual Streamable HTTP server URL + "transport": "streamable-http" +} + +try: + with MCPServerAdapter(server_params) as tools: + print(f"Available tools from Streamable HTTP MCP server: {[tool.name for tool in tools]}") + + http_agent = Agent( + role="HTTP Service Integrator", + goal="Utilize tools from a remote MCP server via Streamable HTTP.", + backstory="An AI agent adept at interacting with complex web services.", + tools=tools, + verbose=True, + ) + + http_task = Task( + description="Perform a complex data query using a tool from the Streamable HTTP server.", + expected_output="The result of the complex data query.", + agent=http_agent, + ) + + http_crew = Crew( + agents=[http_agent], + tasks=[http_task], + verbose=True, + process=Process.sequential + ) + + result = http_crew.kickoff() + print("\nCrew Task Result (Streamable HTTP - Managed):\n", result) + +except Exception as e: + print(f"Error connecting to or using Streamable HTTP MCP server (Managed): {e}") + print("Ensure the Streamable HTTP MCP server is running and accessible at the specified URL.") + +``` +**ملاحظة:** استبدل `"http://localhost:8001/mcp"` بعنوان URL الفعلي لخادم MCP Streamable HTTP الخاص بك. + +### 2. دورة حياة اتصال يدوية + +للسيناريوهات التي تتطلب تحكماً أكثر صراحة، يمكنك إدارة اتصال `MCPServerAdapter` يدوياً. + + +من **الضروري** استدعاء `mcp_server_adapter.stop()` عند الانتهاء لإغلاق الاتصال وتحرير الموارد. كتلة `try...finally` هي الطريقة الأكثر أماناً لضمان ذلك. + + +```python +from crewai import Agent, Task, Crew, Process +from crewai_tools import MCPServerAdapter + +server_params = { + "url": "http://localhost:8001/mcp", # Replace with your actual Streamable HTTP server URL + "transport": "streamable-http" +} + +mcp_server_adapter = None +try: + mcp_server_adapter = MCPServerAdapter(server_params) + mcp_server_adapter.start() + tools = mcp_server_adapter.tools + print(f"Available tools (manual Streamable HTTP): {[tool.name for tool in tools]}") + + manual_http_agent = Agent( + role="Advanced Web Service User", + goal="Interact with an MCP server using manually managed Streamable HTTP connections.", + backstory="An AI specialist in fine-tuning HTTP-based service integrations.", + tools=tools, + verbose=True + ) + + data_processing_task = Task( + description="Submit data for processing and retrieve results via Streamable HTTP.", + expected_output="Processed data or confirmation.", + agent=manual_http_agent + ) + + data_crew = Crew( + agents=[manual_http_agent], + tasks=[data_processing_task], + verbose=True, + process=Process.sequential + ) + + result = data_crew.kickoff() + print("\nCrew Task Result (Streamable HTTP - Manual):\n", result) + +except Exception as e: + print(f"An error occurred during manual Streamable HTTP MCP integration: {e}") + print("Ensure the Streamable HTTP MCP server is running and accessible.") +finally: + if mcp_server_adapter and mcp_server_adapter.is_connected: + print("Stopping Streamable HTTP MCP server connection (manual)...") + mcp_server_adapter.stop() # **Crucial: Ensure stop is called** + elif mcp_server_adapter: + print("Streamable HTTP MCP server adapter was not connected. No stop needed or start failed.") +``` + +## اعتبارات الأمان + +عند استخدام نقل Streamable HTTP، فإن أفضل ممارسات أمان الويب العامة ضرورية: +- **استخدم HTTPS**: فضّل دائماً HTTPS لعناوين URL خوادم MCP لتشفير البيانات أثناء النقل. +- **المصادقة**: نفّذ آليات مصادقة قوية إذا كان خادم MCP يكشف أدوات أو بيانات حساسة. +- **التحقق من المدخلات**: تأكد من أن خادم MCP يتحقق من جميع الطلبات والمعاملات الواردة. + +للحصول على دليل شامل حول تأمين تكاملات MCP، يرجى الرجوع إلى صفحة [اعتبارات الأمان](./security.mdx) ووثائق [أمان نقل MCP](https://modelcontextprotocol.io/docs/concepts/transports#security-considerations) الرسمية. diff --git a/docs/ar/observability/arize-phoenix.mdx b/docs/ar/observability/arize-phoenix.mdx new file mode 100644 index 000000000..239cced3e --- /dev/null +++ b/docs/ar/observability/arize-phoenix.mdx @@ -0,0 +1,150 @@ +--- +title: Arize Phoenix +description: تكامل Arize Phoenix مع CrewAI باستخدام OpenTelemetry و OpenInference +icon: magnifying-glass-chart +mode: "wide" +--- + +# تكامل Arize Phoenix + +يوضح هذا الدليل كيفية دمج **Arize Phoenix** مع **CrewAI** باستخدام OpenTelemetry عبر حزمة [OpenInference](https://github.com/openinference/openinference) SDK. بنهاية هذا الدليل، ستتمكن من تتبع وكلاء CrewAI وتصحيح أخطاء وكلائك بسهولة. + +> **ما هو Arize Phoenix؟** [Arize Phoenix](https://phoenix.arize.com) هو منصة مراقبة LLM توفر التتبع والتقييم لتطبيقات الذكاء الاصطناعي. + +[![شاهد عرض فيديو لتكاملنا مع Phoenix](https://storage.googleapis.com/arize-assets/fixtures/setup_crewai.png)](https://www.youtube.com/watch?v=Yc5q3l6F7Ww) + +## البدء + +سنمر عبر مثال بسيط لاستخدام CrewAI ودمجه مع Arize Phoenix عبر OpenTelemetry باستخدام OpenInference. + +يمكنك أيضاً الوصول إلى هذا الدليل على [Google Colab](https://colab.research.google.com/github/Arize-ai/phoenix/blob/main/tutorials/tracing/crewai_tracing_tutorial.ipynb). + +### الخطوة 1: تثبيت الاعتماديات + +```bash +pip install openinference-instrumentation-crewai crewai crewai-tools arize-phoenix-otel +``` + +### الخطوة 2: إعداد متغيرات البيئة + +قم بإعداد مفاتيح API لـ Phoenix Cloud وإعداد OpenTelemetry لإرسال التتبعات إلى Phoenix. Phoenix Cloud هو إصدار مستضاف من Arize Phoenix، لكنه ليس مطلوباً لاستخدام هذا التكامل. + +يمكنك الحصول على مفتاح Serper API المجاني [هنا](https://serper.dev/). + +```python +import os +from getpass import getpass + +# Get your Phoenix Cloud credentials +PHOENIX_API_KEY = getpass("🔑 Enter your Phoenix Cloud API Key: ") + +# Get API keys for services +OPENAI_API_KEY = getpass("🔑 Enter your OpenAI API key: ") +SERPER_API_KEY = getpass("🔑 Enter your Serper API key: ") + +# Set environment variables +os.environ["PHOENIX_CLIENT_HEADERS"] = f"api_key={PHOENIX_API_KEY}" +os.environ["PHOENIX_COLLECTOR_ENDPOINT"] = "https://app.phoenix.arize.com" # Phoenix Cloud, change this to your own endpoint if you are using a self-hosted instance +os.environ["OPENAI_API_KEY"] = OPENAI_API_KEY +os.environ["SERPER_API_KEY"] = SERPER_API_KEY +``` + +### الخطوة 3: تهيئة OpenTelemetry مع Phoenix + +قم بتهيئة OpenInference OpenTelemetry instrumentation SDK لبدء التقاط التتبعات وإرسالها إلى Phoenix. + +```python +from phoenix.otel import register + +tracer_provider = register( + project_name="crewai-tracing-demo", + auto_instrument=True, +) +``` + +### الخطوة 4: إنشاء تطبيق CrewAI + +سننشئ تطبيق CrewAI حيث يتعاون وكيلان للبحث وكتابة مقال مدونة حول تطورات الذكاء الاصطناعي. + +```python +from crewai import Agent, Crew, Process, Task +from crewai_tools import SerperDevTool +from openinference.instrumentation.crewai import CrewAIInstrumentor +from phoenix.otel import register + +# setup monitoring for your crew +tracer_provider = register( + endpoint="http://localhost:6006/v1/traces") +CrewAIInstrumentor().instrument(skip_dep_check=True, tracer_provider=tracer_provider) +search_tool = SerperDevTool() + +# Define your agents with roles and goals +researcher = Agent( + role="Senior Research Analyst", + goal="Uncover cutting-edge developments in AI and data science", + backstory="""You work at a leading tech think tank. + Your expertise lies in identifying emerging trends. + You have a knack for dissecting complex data and presenting actionable insights.""", + verbose=True, + allow_delegation=False, + tools=[search_tool], +) +writer = Agent( + role="Tech Content Strategist", + goal="Craft compelling content on tech advancements", + backstory="""You are a renowned Content Strategist, known for your insightful and engaging articles. + You transform complex concepts into compelling narratives.""", + verbose=True, + allow_delegation=True, +) + +# Create tasks for your agents +task1 = Task( + description="""Conduct a comprehensive analysis of the latest advancements in AI in 2024. + Identify key trends, breakthrough technologies, and potential industry impacts.""", + expected_output="Full analysis report in bullet points", + agent=researcher, +) + +task2 = Task( + description="""Using the insights provided, develop an engaging blog + post that highlights the most significant AI advancements. + Your post should be informative yet accessible, catering to a tech-savvy audience. + Make it sound cool, avoid complex words so it doesn't sound like AI.""", + expected_output="Full blog post of at least 4 paragraphs", + agent=writer, +) + +# Instantiate your crew with a sequential process +crew = Crew( + agents=[researcher, writer], tasks=[task1, task2], verbose=1, process=Process.sequential +) + +# Get your crew to work! +result = crew.kickoff() + +print("######################") +print(result) +``` + +### الخطوة 5: عرض التتبعات في Phoenix + +بعد تشغيل الوكيل، يمكنك عرض التتبعات المولدة من تطبيق CrewAI في Phoenix. سترى خطوات مفصلة لتفاعلات الوكلاء واستدعاءات LLM، مما يساعدك في التصحيح والتحسين. + +سجل الدخول إلى حساب Phoenix Cloud الخاص بك وانتقل إلى المشروع الذي حددته في معامل `project_name`. سترى عرض زمني للتتبع مع جميع تفاعلات الوكلاء واستخدامات الأدوات واستدعاءات LLM. + +![مثال تتبع في Phoenix يوضح تفاعلات الوكلاء](https://storage.googleapis.com/arize-assets/fixtures/crewai_traces.png) + + +### معلومات التوافق +- Python 3.8+ +- CrewAI >= 0.86.0 +- Arize Phoenix >= 7.0.1 +- OpenTelemetry SDK >= 1.31.0 + + +### المراجع +- [وثائق Phoenix](https://docs.arize.com/phoenix/) - نظرة عامة على منصة Phoenix. +- [وثائق CrewAI](https://docs.crewai.com/) - نظرة عامة على إطار عمل CrewAI. +- [وثائق OpenTelemetry](https://opentelemetry.io/docs/) - دليل OpenTelemetry +- [OpenInference GitHub](https://github.com/openinference/openinference) - الكود المصدري لـ OpenInference SDK. diff --git a/docs/ar/observability/braintrust.mdx b/docs/ar/observability/braintrust.mdx new file mode 100644 index 000000000..7f52d9e92 --- /dev/null +++ b/docs/ar/observability/braintrust.mdx @@ -0,0 +1,232 @@ +--- +title: Braintrust +description: تكامل Braintrust مع CrewAI باستخدام تتبع وتقييم OpenTelemetry +icon: magnifying-glass-chart +mode: "wide" +--- + +# تكامل Braintrust + +يوضح هذا الدليل كيفية دمج **Braintrust** مع **CrewAI** باستخدام OpenTelemetry للتتبع والتقييم الشامل. بنهاية هذا الدليل، ستتمكن من تتبع وكلاء CrewAI ومراقبة أدائهم وتقييم مخرجاتهم باستخدام منصة المراقبة القوية من Braintrust. + +> **ما هو Braintrust؟** [Braintrust](https://www.braintrust.dev) هو منصة تقييم ومراقبة للذكاء الاصطناعي توفر تتبعاً شاملاً وتقييماً ومراقبة لتطبيقات الذكاء الاصطناعي مع تتبع تجارب مدمج وتحليلات أداء. + +## البدء + +سنمر عبر مثال بسيط لاستخدام CrewAI ودمجه مع Braintrust عبر OpenTelemetry للمراقبة والتقييم الشامل. + +### الخطوة 1: تثبيت الاعتماديات + +```bash +uv add braintrust[otel] crewai crewai-tools opentelemetry-instrumentation-openai opentelemetry-instrumentation-crewai python-dotenv +``` + +### الخطوة 2: إعداد متغيرات البيئة + +قم بإعداد مفاتيح API لـ Braintrust وإعداد OpenTelemetry لإرسال التتبعات إلى Braintrust. ستحتاج إلى مفتاح API من Braintrust ومفتاح API من OpenAI. + +```python +import os +from getpass import getpass + +# Get your Braintrust credentials +BRAINTRUST_API_KEY = getpass("🔑 Enter your Braintrust API Key: ") + +# Get API keys for services +OPENAI_API_KEY = getpass("🔑 Enter your OpenAI API key: ") + +# Set environment variables +os.environ["BRAINTRUST_API_KEY"] = BRAINTRUST_API_KEY +os.environ["BRAINTRUST_PARENT"] = "project_name:crewai-demo" +os.environ["OPENAI_API_KEY"] = OPENAI_API_KEY +``` + +### الخطوة 3: تهيئة OpenTelemetry مع Braintrust + +قم بتهيئة أداة Braintrust OpenTelemetry لبدء التقاط التتبعات وإرسالها إلى Braintrust. + +```python +import os +from typing import Any, Dict + +from braintrust.otel import BraintrustSpanProcessor +from crewai import Agent, Crew, Task +from crewai.llm import LLM +from opentelemetry import trace +from opentelemetry.instrumentation.crewai import CrewAIInstrumentor +from opentelemetry.instrumentation.openai import OpenAIInstrumentor +from opentelemetry.sdk.trace import TracerProvider + +def setup_tracing() -> None: + """Setup OpenTelemetry tracing with Braintrust.""" + current_provider = trace.get_tracer_provider() + if isinstance(current_provider, TracerProvider): + provider = current_provider + else: + provider = TracerProvider() + trace.set_tracer_provider(provider) + + provider.add_span_processor(BraintrustSpanProcessor()) + CrewAIInstrumentor().instrument(tracer_provider=provider) + OpenAIInstrumentor().instrument(tracer_provider=provider) + + +setup_tracing() +``` + +### الخطوة 4: إنشاء تطبيق CrewAI + +سننشئ تطبيق CrewAI حيث يتعاون وكيلان للبحث وكتابة مقال مدونة حول تطورات الذكاء الاصطناعي، مع تفعيل التتبع الشامل. + +```python +from crewai import Agent, Crew, Process, Task +from crewai_tools import SerperDevTool + +def create_crew() -> Crew: + """Create a crew with multiple agents for comprehensive tracing.""" + llm = LLM(model="gpt-4o-mini") + search_tool = SerperDevTool() + + researcher = Agent( + role="Senior Research Analyst", + goal="Uncover cutting-edge developments in AI and data science", + backstory="""You work at a leading tech think tank. + Your expertise lies in identifying emerging trends. + You have a knack for dissecting complex data and presenting actionable insights.""", + verbose=True, + allow_delegation=False, + llm=llm, + tools=[search_tool], + ) + + writer = Agent( + role="Tech Content Strategist", + goal="Craft compelling content on tech advancements", + backstory="""You are a renowned Content Strategist, known for your insightful and engaging articles. + You transform complex concepts into compelling narratives.""", + verbose=True, + allow_delegation=True, + llm=llm, + ) + + research_task = Task( + description="""Conduct a comprehensive analysis of the latest advancements in {topic}. + Identify key trends, breakthrough technologies, and potential industry impacts.""", + expected_output="Full analysis report in bullet points", + agent=researcher, + ) + + writing_task = Task( + description="""Using the insights provided, develop an engaging blog + post that highlights the most significant {topic} advancements. + Your post should be informative yet accessible, catering to a tech-savvy audience. + Make it sound cool, avoid complex words so it doesn't sound like AI.""", + expected_output="Full blog post of at least 4 paragraphs", + agent=writer, + context=[research_task], + ) + + crew = Crew( + agents=[researcher, writer], + tasks=[research_task, writing_task], + verbose=True, + process=Process.sequential + ) + + return crew + +def run_crew(): + """Run the crew and return results.""" + crew = create_crew() + result = crew.kickoff(inputs={"topic": "AI developments"}) + return result + +if __name__ == "__main__": + result = run_crew() + print(result) +``` + +### الخطوة 5: عرض التتبعات في Braintrust + +بعد تشغيل طاقمك، يمكنك عرض تتبعات شاملة في Braintrust من خلال وجهات نظر مختلفة: + + + + + عرض تتبع Braintrust + + + + + + عرض الجدول الزمني Braintrust + + + + + + عرض المحادثة Braintrust + + + + +### الخطوة 6: التقييم عبر SDK (التجارب) + +يمكنك أيضاً تشغيل التقييمات باستخدام Braintrust Eval SDK. هذا مفيد لمقارنة الإصدارات أو تسجيل المخرجات. فيما يلي مثال Python باستخدام فئة `Eval`: + +```python +# eval_crew.py +from braintrust import Eval +from autoevals import Levenshtein + +def evaluate_crew_task(input_data): + """Task function that wraps our crew for evaluation.""" + crew = create_crew() + result = crew.kickoff(inputs={"topic": input_data["topic"]}) + return str(result) + +Eval( + "AI Research Crew", + { + "data": lambda: [ + {"topic": "artificial intelligence trends 2024"}, + {"topic": "machine learning breakthroughs"}, + {"topic": "AI ethics and governance"}, + ], + "task": evaluate_crew_task, + "scores": [Levenshtein], + }, +) +``` + +قم بإعداد مفتاح API الخاص بك وشغّل: + +```bash +export BRAINTRUST_API_KEY="YOUR_API_KEY" +braintrust eval eval_crew.py +``` + +راجع [دليل Braintrust Eval SDK](https://www.braintrust.dev/docs/start/eval-sdk) لمزيد من التفاصيل. + +### الميزات الرئيسية لتكامل Braintrust + +- **تتبع شامل**: تتبع جميع تفاعلات الوكلاء واستخدام الأدوات واستدعاءات LLM +- **مراقبة الأداء**: مراقبة أوقات التنفيذ واستخدام الرموز ومعدلات النجاح +- **تتبع التجارب**: مقارنة إعدادات الطاقم والنماذج المختلفة +- **التقييم الآلي**: إعداد مقاييس تقييم مخصصة لمخرجات الطاقم +- **تتبع الأخطاء**: مراقبة وتصحيح حالات الفشل عبر عمليات تنفيذ الطاقم +- **تحليل التكاليف**: تتبع استخدام الرموز والتكاليف المرتبطة + +### معلومات التوافق +- Python 3.8+ +- CrewAI >= 0.86.0 +- Braintrust >= 0.1.0 +- OpenTelemetry SDK >= 1.31.0 + +### المراجع +- [وثائق Braintrust](https://www.braintrust.dev/docs) - نظرة عامة على منصة Braintrust +- [تكامل Braintrust CrewAI](https://www.braintrust.dev/docs/integrations/crew-ai) - دليل التكامل الرسمي مع CrewAI +- [Braintrust Eval SDK](https://www.braintrust.dev/docs/start/eval-sdk) - تشغيل التجارب عبر SDK +- [وثائق CrewAI](https://docs.crewai.com/) - نظرة عامة على إطار عمل CrewAI +- [وثائق OpenTelemetry](https://opentelemetry.io/docs/) - دليل OpenTelemetry +- [Braintrust GitHub](https://github.com/braintrustdata/braintrust) - الكود المصدري لـ Braintrust SDK diff --git a/docs/ar/observability/datadog.mdx b/docs/ar/observability/datadog.mdx new file mode 100644 index 000000000..0d6ebebe9 --- /dev/null +++ b/docs/ar/observability/datadog.mdx @@ -0,0 +1,109 @@ +--- +title: تكامل Datadog +description: تعلم كيفية دمج Datadog مع CrewAI لإرسال تتبعات مراقبة LLM إلى Datadog. +icon: dog +mode: "wide" +--- + +# دمج Datadog مع CrewAI + +سيوضح هذا الدليل كيفية دمج **[Datadog LLM Observability](https://docs.datadoghq.com/llm_observability/)** مع **CrewAI** باستخدام [أداة Datadog للتجهيز التلقائي](https://docs.datadoghq.com/llm_observability/instrumentation/auto_instrumentation?tab=python). بنهاية هذا الدليل، ستتمكن من إرسال تتبعات مراقبة LLM إلى Datadog وعرض تشغيلات وكلاء CrewAI في [عرض التنفيذ الوكيلي](https://docs.datadoghq.com/llm_observability/monitoring/agent_monitoring) من Datadog LLM Observability. + +## ما هو Datadog LLM Observability؟ + +[Datadog LLM Observability](https://www.datadoghq.com/product/llm-observability/) يساعد مهندسي الذكاء الاصطناعي وعلماء البيانات ومطوري التطبيقات على تطوير وتقييم ومراقبة تطبيقات LLM بسرعة. حسّن جودة المخرجات والأداء والتكاليف والمخاطر الإجمالية بثقة مع تجارب منظمة وتتبع شامل عبر وكلاء الذكاء الاصطناعي والتقييمات. + +## البدء + +### تثبيت الاعتماديات + +```shell +pip install ddtrace crewai crewai-tools +``` + +### تعيين متغيرات البيئة + +إذا لم يكن لديك مفتاح API من Datadog، يمكنك [إنشاء حساب](https://www.datadoghq.com/) و[الحصول على مفتاح API](https://docs.datadoghq.com/account_management/api-app-keys/#api-keys). + +ستحتاج أيضاً إلى تحديد اسم تطبيق ML في متغيرات البيئة التالية. تطبيق ML هو تجميع لتتبعات LLM Observability المرتبطة بتطبيق محدد قائم على LLM. + +```shell +export DD_API_KEY= +export DD_SITE= +export DD_LLMOBS_ENABLED=true +export DD_LLMOBS_ML_APP= +export DD_LLMOBS_AGENTLESS_ENABLED=true +export DD_APM_TRACING_ENABLED=false +``` + +بالإضافة إلى ذلك، قم بإعداد مفاتيح API لمزودي LLM + +```shell +export OPENAI_API_KEY= +export ANTHROPIC_API_KEY= +export GEMINI_API_KEY= +... +``` + +### إنشاء تطبيق وكيل CrewAI + +```python +# crewai_agent.py +from crewai import Agent, Task, Crew + +from crewai_tools import ( + WebsiteSearchTool +) + +web_rag_tool = WebsiteSearchTool() + +writer = Agent( + role="Writer", + goal="You make math engaging and understandable for young children through poetry", + backstory="You're an expert in writing haikus but you know nothing of math.", + tools=[web_rag_tool], +) + +task = Task( + description=("What is {multiplication}?"), + expected_output=("Compose a haiku that includes the answer."), + agent=writer +) + +crew = Crew( + agents=[writer], + tasks=[task], + share_crew=False +) + +output = crew.kickoff(dict(multiplication="2 * 2")) +``` + +### تشغيل التطبيق مع التجهيز التلقائي من Datadog + +مع تعيين [متغيرات البيئة](#تعيين-متغيرات-البيئة)، يمكنك الآن تشغيل التطبيق مع التجهيز التلقائي من Datadog. + +```shell +ddtrace-run python crewai_agent.py +``` + +### عرض التتبعات في Datadog + +بعد تشغيل التطبيق، يمكنك عرض التتبعات في [عرض تتبعات Datadog LLM Observability](https://app.datadoghq.com/llm/traces)، باختيار اسم تطبيق ML الذي اخترته من القائمة المنسدلة أعلى اليسار. + +النقر على تتبع سيعرض لك تفاصيل التتبع، بما في ذلك إجمالي الرموز المستخدمة وعدد استدعاءات LLM والنماذج المستخدمة والتكلفة المقدرة. + + +عرض تتبع Datadog LLM Observability + + +بالإضافة إلى ذلك، يمكنك عرض رسم بياني لتنفيذ التتبع، الذي يوضح تدفق التحكم والبيانات للتتبع. + + +عرض تدفق تنفيذ وكيل Datadog LLM Observability + + +## المراجع + +- [Datadog LLM Observability](https://www.datadoghq.com/product/llm-observability/) +- [التجهيز التلقائي لـ CrewAI من Datadog LLM Observability](https://docs.datadoghq.com/llm_observability/instrumentation/auto_instrumentation?tab=python#crew-ai) diff --git a/docs/ar/observability/galileo.mdx b/docs/ar/observability/galileo.mdx new file mode 100644 index 000000000..9c51f2306 --- /dev/null +++ b/docs/ar/observability/galileo.mdx @@ -0,0 +1,86 @@ +--- +title: Galileo +description: تكامل Galileo مع CrewAI للتتبع والتقييم +icon: telescope +mode: "wide" +--- + +## نظرة عامة + +يوضح هذا الدليل كيفية دمج **Galileo** مع **CrewAI** للتتبع الشامل وهندسة التقييم. بنهاية هذا الدليل، ستتمكن من تتبع وكلاء CrewAI ومراقبة أدائهم وتقييم سلوكهم باستخدام منصة المراقبة القوية من Galileo. + +> **ما هو Galileo؟** [Galileo](https://galileo.ai) هو منصة تقييم ومراقبة للذكاء الاصطناعي توفر تتبعاً شاملاً وتقييماً ومراقبة لتطبيقات الذكاء الاصطناعي. تمكّن الفرق من التقاط البيانات الحقيقية وإنشاء حواجز قوية وتشغيل تجارب منهجية مع تتبع تجارب مدمج وتحليلات أداء. + +## البدء + +يتبع هذا البرنامج التعليمي [البدء السريع مع CrewAI](/ar/quickstart) ويوضح كيفية إضافة [CrewAIEventListener](https://v2docs.galileo.ai/sdk-api/python/reference/handlers/crewai/handler) من Galileo كمعالج أحداث. + +> **ملاحظة** يفترض هذا البرنامج التعليمي أنك أكملت [البدء السريع مع CrewAI](/ar/quickstart). + +### الخطوة 1: تثبيت الاعتماديات + +ثبّت الاعتماديات المطلوبة لتطبيقك: + +```bash +uv add galileo +``` + +### الخطوة 2: أضف إلى ملف .env من [البدء السريع مع CrewAI](/ar/quickstart) + +```bash +# Your Galileo API key +GALILEO_API_KEY="your-galileo-api-key" + +# Your Galileo project name +GALILEO_PROJECT="your-galileo-project-name" + +# The name of the Log stream you want to use for logging +GALILEO_LOG_STREAM="your-galileo-log-stream " +``` + +### الخطوة 3: إضافة مستمع أحداث Galileo + +لتفعيل التسجيل مع Galileo، تحتاج إلى إنشاء مثيل من `CrewAIEventListener`. استورد حزمة معالج CrewAI من Galileo بإضافة الكود التالي في أعلى ملف main.py: + +```python +from galileo.handlers.crewai.handler import CrewAIEventListener +``` + +في بداية دالة التشغيل، أنشئ مستمع الأحداث: + +```python +def run(): + # Create the event listener + CrewAIEventListener() + # The rest of your existing code goes here +``` + +عند إنشاء مثيل المستمع، يتم تسجيله تلقائياً مع CrewAI. + +### الخطوة 4: شغّل طاقمك + +شغّل طاقمك باستخدام CrewAI CLI: + +```bash +crewai run +``` + +### الخطوة 5: عرض التتبعات في Galileo + +بمجرد انتهاء طاقمك، سيتم تفريغ التتبعات وستظهر في Galileo. + +![عرض تتبع Galileo](/images/galileo-trace-veiw.png) + +## فهم تكامل Galileo + +يتكامل Galileo مع CrewAI عن طريق تسجيل مستمع أحداث يلتقط أحداث تنفيذ الطاقم (مثل إجراءات الوكلاء واستدعاءات الأدوات واستجابات النماذج) ويعيد توجيهها إلى Galileo للمراقبة والتقييم. + +### فهم مستمع الأحداث + +إنشاء مثيل `CrewAIEventListener()` هو كل ما يلزم لتفعيل Galileo لتشغيل CrewAI. عند الإنشاء، يقوم المستمع بـ: + +- التسجيل تلقائياً مع CrewAI +- قراءة إعدادات Galileo من متغيرات البيئة +- تسجيل جميع بيانات التشغيل في مشروع Galileo وتدفق السجل المحدد بواسطة `GALILEO_PROJECT` و `GALILEO_LOG_STREAM` + +لا يلزم أي إعداد إضافي أو تغييرات في الكود. diff --git a/docs/ar/observability/langdb.mdx b/docs/ar/observability/langdb.mdx new file mode 100644 index 000000000..42726faaa --- /dev/null +++ b/docs/ar/observability/langdb.mdx @@ -0,0 +1,167 @@ +--- +title: تكامل LangDB +description: إدارة وتأمين وتحسين سير عمل CrewAI مع بوابة LangDB AI — الوصول إلى أكثر من 350 نموذجاً وتوجيه تلقائي وتحسين التكاليف ومراقبة كاملة. +icon: database +mode: "wide" +--- + +# مقدمة + +توفر [بوابة LangDB AI](https://langdb.ai) واجهات API متوافقة مع OpenAI للاتصال بنماذج لغة كبيرة متعددة وتعمل كمنصة مراقبة تجعل تتبع سير عمل CrewAI شاملاً وسهلاً مع توفير الوصول إلى أكثر من 350 نموذج لغة. مع استدعاء `init()` واحد، يتم التقاط جميع تفاعلات الوكلاء وتنفيذ المهام واستدعاءات LLM، مما يوفر مراقبة شاملة وبنية تحتية جاهزة للإنتاج لتطبيقاتك. + + + مثال تتبع LangDB CrewAI + + +**تحقق من:** [عرض مثال التتبع المباشر](https://app.langdb.ai/sharing/threads/3becbfed-a1be-ae84-ea3c-4942867a3e22) + +## الميزات + +### قدرات بوابة AI +- **الوصول إلى أكثر من 350 LLM**: الاتصال بجميع نماذج اللغة الرئيسية من خلال تكامل واحد +- **النماذج الافتراضية**: إنشاء إعدادات نماذج مخصصة مع معاملات وقواعد توجيه محددة +- **MCP الافتراضي**: تفعيل التوافق والتكامل مع أنظمة MCP لتعزيز اتصال الوكلاء +- **حواجز الحماية**: تنفيذ تدابير السلامة وضوابط الامتثال لسلوك الوكلاء + +### المراقبة والتتبع +- **تتبع تلقائي**: استدعاء `init()` واحد يلتقط جميع تفاعلات CrewAI +- **رؤية شاملة**: مراقبة سير عمل الوكلاء من البداية إلى النهاية +- **تتبع استخدام الأدوات**: تتبع الأدوات التي يستخدمها الوكلاء ونتائجها +- **مراقبة استدعاءات النماذج**: رؤى مفصلة لتفاعلات LLM +- **تحليلات الأداء**: مراقبة زمن الاستجابة واستخدام الرموز والتكاليف +- **دعم التصحيح**: تنفيذ خطوة بخطوة لاستكشاف الأخطاء +- **المراقبة في الوقت الفعلي**: لوحة معلومات التتبعات والمقاييس الحية + +## تعليمات الإعداد + + + + ثبّت عميل LangDB مع علامة ميزة CrewAI: + ```bash + pip install 'pylangdb[crewai]' + ``` + + + قم بإعداد بيانات اعتماد LangDB: + ```bash + export LANGDB_API_KEY="" + export LANGDB_PROJECT_ID="" + export LANGDB_API_BASE_URL='https://api.us-east-1.langdb.ai' + ``` + + + استورد وهيّئ LangDB قبل إعداد كود CrewAI: + ```python + from pylangdb.crewai import init + # Initialize LangDB + init() + ``` + + + قم بإعداد LLM مع رؤوس LangDB: + ```python + from crewai import Agent, Task, Crew, LLM + import os + + # Configure LLM with LangDB headers + llm = LLM( + model="openai/gpt-4o", + api_key=os.getenv("LANGDB_API_KEY"), + base_url=os.getenv("LANGDB_API_BASE_URL"), + extra_headers={"x-project-id": os.getenv("LANGDB_PROJECT_ID")} + ) + ``` + + + +## مثال سريع للبدء + +```python +import os +from pylangdb.crewai import init +from crewai import Agent, Task, Crew, LLM + +init() + +def create_llm(model): + return LLM( + model=model, + api_key=os.environ.get("LANGDB_API_KEY"), + base_url=os.environ.get("LANGDB_API_BASE_URL"), + extra_headers={"x-project-id": os.environ.get("LANGDB_PROJECT_ID")} + ) + +researcher = Agent( + role="Research Specialist", + goal="Research topics thoroughly", + backstory="Expert researcher with skills in finding information", + llm=create_llm("openai/gpt-4o"), + verbose=True +) + +task = Task( + description="Research the given topic and provide a comprehensive summary", + agent=researcher, + expected_output="Detailed research summary with key findings" +) + +crew = Crew(agents=[researcher], tasks=[task]) +result = crew.kickoff() +print(result) +``` + +## عرض التتبعات في LangDB + +بعد تشغيل تطبيق CrewAI، يمكنك عرض تتبعات مفصلة في لوحة معلومات LangDB: + + + لوحة معلومات تتبع LangDB تعرض سير عمل CrewAI + + +### ما ستراه + +- **تفاعلات الوكلاء**: التدفق الكامل لمحادثات الوكلاء وتسليم المهام +- **استخدام الأدوات**: الأدوات التي تم استدعاؤها ومدخلاتها ومخرجاتها +- **استدعاءات النماذج**: تفاعلات LLM المفصلة مع المطالبات والاستجابات +- **مقاييس الأداء**: تتبع زمن الاستجابة واستخدام الرموز والتكاليف +- **الجدول الزمني للتنفيذ**: عرض خطوة بخطوة لسير العمل بالكامل + +## استكشاف الأخطاء وإصلاحها + +### المشاكل الشائعة + +- **عدم ظهور تتبعات**: تأكد من استدعاء `init()` قبل أي استيرادات CrewAI +- **أخطاء المصادقة**: تحقق من مفتاح API ومعرف المشروع في LangDB + +## الموارد + + + + الوثائق والأدلة الرسمية لـ LangDB + + + برامج تعليمية خطوة بخطوة لبناء وكلاء AI + + + أمثلة تكامل CrewAI الكاملة + + + الوصول إلى تتبعاتك وتحليلاتك + + + تصفح أكثر من 350 نموذج لغة متاح + + + خيارات الاستضافة الذاتية وقدرات المؤسسات + + + +## الخطوات التالية + +غطى هذا الدليل أساسيات دمج بوابة LangDB AI مع CrewAI. لتعزيز سير عمل الذكاء الاصطناعي بشكل أكبر، استكشف: + +- **النماذج الافتراضية**: إنشاء إعدادات نماذج مخصصة مع استراتيجيات توجيه +- **حواجز الحماية والسلامة**: تنفيذ تصفية المحتوى وضوابط الامتثال +- **النشر في الإنتاج**: إعداد خطط احتياطية وإعادة المحاولة وتوازن الأحمال + +لمزيد من الميزات المتقدمة وحالات الاستخدام، زُر [وثائق LangDB](https://docs.langdb.ai) أو استكشف [كتالوج النماذج](https://app.langdb.ai/models) لاكتشاف جميع النماذج المتاحة. diff --git a/docs/ar/observability/langfuse.mdx b/docs/ar/observability/langfuse.mdx new file mode 100644 index 000000000..e62d2e657 --- /dev/null +++ b/docs/ar/observability/langfuse.mdx @@ -0,0 +1,109 @@ +--- +title: تكامل Langfuse +description: تعلم كيفية دمج Langfuse مع CrewAI عبر OpenTelemetry باستخدام OpenLit +icon: vials +mode: "wide" +--- + +# دمج Langfuse مع CrewAI + +يوضح هذا الدفتر كيفية دمج **Langfuse** مع **CrewAI** باستخدام OpenTelemetry عبر حزمة **OpenLit** SDK. بنهاية هذا الدفتر، ستتمكن من تتبع تطبيقات CrewAI مع Langfuse لتحسين المراقبة والتصحيح. + +> **ما هو Langfuse؟** [Langfuse](https://langfuse.com) هو منصة هندسة LLM مفتوحة المصدر. توفر قدرات التتبع والمراقبة لتطبيقات LLM، مما يساعد المطورين على التصحيح والتحليل والتحسين. يتكامل Langfuse مع أدوات وأطر عمل متنوعة عبر تكاملات أصلية وOpenTelemetry وواجهات API/SDKs. + +[![فيديو نظرة عامة على Langfuse](https://github.com/user-attachments/assets/3926b288-ff61-4b95-8aa1-45d041c70866)](https://langfuse.com/watch-demo) + +## البدء + +سنمر عبر مثال بسيط لاستخدام CrewAI ودمجه مع Langfuse عبر OpenTelemetry باستخدام OpenLit. + +### الخطوة 1: تثبيت الاعتماديات + +```python +%pip install langfuse openlit crewai crewai_tools +``` + +### الخطوة 2: إعداد متغيرات البيئة + +عيّن مفاتيح API لـ Langfuse وإعدادات تصدير OpenTelemetry لإرسال التتبعات إلى Langfuse. يرجى الرجوع إلى [وثائق Langfuse OpenTelemetry](https://langfuse.com/docs/opentelemetry/get-started) لمزيد من المعلومات. + +```python +import os + +# Get keys for your project from the project settings page: https://cloud.langfuse.com +os.environ["LANGFUSE_PUBLIC_KEY"] = "pk-lf-..." +os.environ["LANGFUSE_SECRET_KEY"] = "sk-lf-..." +os.environ["LANGFUSE_HOST"] = "https://cloud.langfuse.com" # 🇪🇺 EU region +# os.environ["LANGFUSE_HOST"] = "https://us.cloud.langfuse.com" # 🇺🇸 US region + + +# Your OpenAI key +os.environ["OPENAI_API_KEY"] = "sk-proj-..." +``` + +مع تعيين متغيرات البيئة، يمكننا الآن تهيئة عميل Langfuse. تهيئ `get_client()` عميل Langfuse باستخدام بيانات الاعتماد المقدمة في متغيرات البيئة. + +```python +from langfuse import get_client + +langfuse = get_client() + +# Verify connection +if langfuse.auth_check(): + print("Langfuse client is authenticated and ready!") +else: + print("Authentication failed. Please check your credentials and host.") +``` + +### الخطوة 3: تهيئة OpenLit + +قم بتهيئة OpenLit OpenTelemetry instrumentation SDK لبدء التقاط تتبعات OpenTelemetry. + +```python +import openlit + +openlit.init() +``` + +### الخطوة 4: إنشاء تطبيق CrewAI بسيط + +سننشئ تطبيق CrewAI بسيط حيث يتعاون عدة وكلاء للإجابة على سؤال المستخدم. + +```python +from crewai import Agent, Task, Crew + +from crewai_tools import ( + WebsiteSearchTool +) + +web_rag_tool = WebsiteSearchTool() + +writer = Agent( + role="Writer", + goal="You make math engaging and understandable for young children through poetry", + backstory="You're an expert in writing haikus but you know nothing of math.", + tools=[web_rag_tool], + ) + +task = Task(description=("What is {multiplication}?"), + expected_output=("Compose a haiku that includes the answer."), + agent=writer) + +crew = Crew( + agents=[writer], + tasks=[task], + share_crew=False +) +``` + +### الخطوة 5: عرض التتبعات في Langfuse + +بعد تشغيل الوكيل، يمكنك عرض التتبعات المولدة من تطبيق CrewAI في [Langfuse](https://cloud.langfuse.com). سترى خطوات مفصلة لتفاعلات LLM، مما يساعدك في التصحيح والتحسين. + +![مثال تتبع CrewAI في Langfuse](https://langfuse.com/images/cookbook/integration_crewai/crewai-example-trace.png) + +_[مثال تتبع عام في Langfuse](https://cloud.langfuse.com/project/cloramnkj0002jz088vzn1ja4/traces/e2cf380ffc8d47d28da98f136140642b?timestamp=2025-02-05T15%3A12%3A02.717Z&observation=3b32338ee6a5d9af)_ + +## المراجع + +- [وثائق Langfuse OpenTelemetry](https://langfuse.com/docs/opentelemetry/get-started) diff --git a/docs/ar/observability/langtrace.mdx b/docs/ar/observability/langtrace.mdx new file mode 100644 index 000000000..d07f3f35e --- /dev/null +++ b/docs/ar/observability/langtrace.mdx @@ -0,0 +1,73 @@ +--- +title: تكامل Langtrace +description: كيفية مراقبة التكلفة وزمن الاستجابة وأداء وكلاء CrewAI باستخدام Langtrace، أداة مراقبة خارجية. +icon: chart-line +mode: "wide" +--- + +# نظرة عامة على Langtrace + +Langtrace هو أداة مفتوحة المصدر خارجية تساعدك في إعداد المراقبة والتقييمات لنماذج اللغة الكبيرة (LLMs) وأطر عمل LLM وقواعد بيانات المتجهات. +على الرغم من أنها ليست مبنية مباشرة في CrewAI، يمكن استخدام Langtrace جنباً إلى جنب مع CrewAI للحصول على رؤية عميقة في التكلفة وزمن الاستجابة وأداء وكلاء CrewAI. +يتيح لك هذا التكامل تسجيل المعاملات الفائقة ومراقبة تراجعات الأداء وإنشاء عملية للتحسين المستمر لوكلائك. + +![نظرة عامة على سلسلة مختارة من جلسات تشغيل الوكلاء](/images/langtrace1.png) +![نظرة عامة على تتبعات الوكلاء](/images/langtrace2.png) +![نظرة عامة على تتبعات LLM بالتفصيل](/images/langtrace3.png) + +## تعليمات الإعداد + + + + سجّل بزيارة [https://langtrace.ai/signup](https://langtrace.ai/signup). + + + عيّن نوع المشروع إلى `CrewAI` وقم بتوليد مفتاح API. + + + استخدم الأمر التالي: + + ```bash + pip install langtrace-python-sdk + ``` + + + استورد وهيّئ Langtrace في بداية نصك البرمجي، قبل أي استيرادات CrewAI: + + ```python + from langtrace_python_sdk import langtrace + langtrace.init(api_key='') + + # Now import CrewAI modules + from crewai import Agent, Task, Crew + ``` + + + +### الميزات وتطبيقاتها على CrewAI + +1. **تتبع رموز LLM والتكاليف** + + - مراقبة استخدام الرموز والتكاليف المرتبطة لكل تفاعل وكيل CrewAI. + +2. **رسم بياني للتتبع لخطوات التنفيذ** + + - تصور تدفق تنفيذ مهام CrewAI، بما في ذلك زمن الاستجابة والسجلات. + - مفيد لتحديد الاختناقات في سير عمل الوكلاء. + +3. **تنظيم مجموعات البيانات مع التعليق اليدوي** + + - إنشاء مجموعات بيانات من مخرجات مهام CrewAI للتدريب أو التقييم المستقبلي. + +4. **إدارة إصدارات المطالبات** + + - تتبع الإصدارات المختلفة من المطالبات المستخدمة في وكلاء CrewAI. + - مفيد لاختبار A/B وتحسين أداء الوكلاء. + +5. **ساحة المطالبات مع مقارنات النماذج** + + - اختبار ومقارنة مطالبات ونماذج مختلفة لوكلاء CrewAI قبل النشر. + +6. **الاختبارات والتقييمات** + + - إعداد اختبارات آلية لوكلاء ومهام CrewAI. diff --git a/docs/ar/observability/maxim.mdx b/docs/ar/observability/maxim.mdx new file mode 100644 index 000000000..dd311643b --- /dev/null +++ b/docs/ar/observability/maxim.mdx @@ -0,0 +1,221 @@ +--- +title: "تكامل Maxim" +description: "بدء مراقبة وتقييم ومراقبة الوكلاء" +icon: "infinity" +mode: "wide" +--- + +# نظرة عامة على Maxim + +يوفر Maxim AI مراقبة شاملة للوكلاء وتقييماً ومراقبة لتطبيقات CrewAI. مع تكامل Maxim بسطر واحد، يمكنك بسهولة تتبع وتحليل تفاعلات الوكلاء ومقاييس الأداء والمزيد. + +## الميزات + +### إدارة المطالبات + +تمكّنك قدرات إدارة المطالبات في Maxim من إنشاء وتنظيم وتحسين المطالبات لوكلاء CrewAI. بدلاً من ترميز التعليمات مباشرة، استفد من SDK الخاص بـ Maxim لاسترداد وتطبيق مطالبات مُدارة بالإصدارات ديناميكياً. + + + + أنشئ وصقل وجرّب وانشر مطالباتك عبر الساحة. نظّم مطالباتك باستخدام المجلدات والإصدارات، وجرّب مع حالات العالم الحقيقي عن طريق ربط الأدوات والسياق، وانشر بناءً على منطق مخصص. + + + + + مع بناء الفرق لتطبيقات الذكاء الاصطناعي، يُعد جزء كبير من التجريب هو التكرار على هيكل المطالبات. للتعاون بفعالية وتنظيم التغييرات بوضوح، يسمح Maxim بإصدارات المطالبات ومقارنة التشغيلات عبر الإصدارات. + + + + + التكرار على المطالبات أثناء تطوير تطبيق الذكاء الاصطناعي يحتاج تجارب عبر النماذج وهياكل المطالبات وغيرها. لمقارنة الإصدارات واتخاذ قرارات مستنيرة، تسمح ساحة المقارنة بعرض جنب إلى جنب للنتائج. + + ## **لماذا تستخدم مقارنة المطالبات؟** + + تجمع مقارنة المطالبات عدة مطالبات فردية في عرض واحد، مما يمكّن من نهج مبسط لسير عمل متنوع: + + 1. **مقارنة النماذج**: تقييم أداء نماذج مختلفة على نفس المطالبة. + 2. **تحسين المطالبات**: مقارنة إصدارات مختلفة لتحديد الصياغة الأكثر فعالية. + 3. **اتساق عبر النماذج**: ضمان مخرجات متسقة عبر نماذج مختلفة لنفس المطالبة. + 4. **قياس الأداء**: تحليل مقاييس مثل زمن الاستجابة والتكلفة وعدد الرموز عبر نماذج ومطالبات مختلفة. + + + +### المراقبة والتقييمات + +يوفر Maxim AI مراقبة وتقييماً شاملاً لوكلاء CrewAI، مما يساعدك في فهم ما يحدث بالضبط أثناء كل تنفيذ. + + + + تتبع دورة حياة وكيلك الكاملة، بما في ذلك استدعاءات الأدوات ومسارات الوكلاء وتدفقات القرار بسهولة. + + + + + شغّل تقييمات مفصلة على التتبعات الكاملة أو العقد الفردية مع دعم لـ: + + - التفاعلات متعددة الخطوات وتحليل التتبع الدقيق + - تقييمات على مستوى الجلسة + - محاكاة لاختبار العالم الحقيقي + + + + + +

+ تقييم السجلات الملتقطة تلقائياً من واجهة المستخدم بناءً على المرشحات والعينات +

+ + +

+ استخدام التقييم البشري أو التصنيف لتقييم جودة سجلاتك +

+ + +

+ تقييم أي مكون من تتبعك أو سجلك للحصول على رؤى حول سلوك وكيلك +

+ + + --- + + + عيّن حدوداً على **الأخطاء والتكلفة واستخدام الرموز وتغذية المستخدم الراجعة وزمن الاستجابة** واحصل على تنبيهات فورية عبر Slack أو PagerDuty. + + + + + تصور التتبعات عبر الزمن ومقاييس الاستخدام وزمن الاستجابة ومعدلات الأخطاء بسهولة. + + + + + +## البدء + +### المتطلبات الأساسية + +- إصدار Python >= 3.10 +- حساب Maxim ([سجّل هنا](https://getmaxim.ai/)) +- توليد مفتاح API من Maxim +- مشروع CrewAI + +### التثبيت + +ثبّت Maxim SDK عبر pip: + +```python +pip install maxim-py +``` + +أو أضفه إلى ملف `requirements.txt`: + +``` +maxim-py +``` + +### الإعداد الأساسي + +### 1. إعداد متغيرات البيئة + +```python +### Environment Variables Setup + +# Create a `.env` file in your project root: + +# Maxim API Configuration +MAXIM_API_KEY=your_api_key_here +MAXIM_LOG_REPO_ID=your_repo_id_here +``` + +### 2. استيراد الحزم المطلوبة + +```python +from crewai import Agent, Task, Crew, Process +from maxim import Maxim +from maxim.logger.crewai import instrument_crewai +``` + +### 3. تهيئة Maxim بمفتاح API + +```python {8} +# Instrument CrewAI with just one line +instrument_crewai(Maxim().logger()) +``` + +### 4. إنشاء وتشغيل تطبيق CrewAI كالمعتاد + +```python +# Create your agent +researcher = Agent( + role='Senior Research Analyst', + goal='Uncover cutting-edge developments in AI', + backstory="You are an expert researcher at a tech think tank...", + verbose=True, + llm=llm +) + +# Define the task +research_task = Task( + description="Research the latest AI advancements...", + expected_output="", + agent=researcher +) + +# Configure and run the crew +crew = Crew( + agents=[researcher], + tasks=[research_task], + verbose=True +) + +try: + result = crew.kickoff() +finally: + maxim.cleanup() # Ensure cleanup happens even if errors occur +``` + +هذا كل شيء! سيتم الآن تسجيل جميع تفاعلات وكلاء CrewAI وستكون متاحة في لوحة معلومات Maxim. + +تحقق من دفتر Google Colab هذا كمرجع سريع - [الدفتر](https://colab.research.google.com/drive/1ZKIZWsmgQQ46n8TH9zLsT1negKkJA6K8?usp=sharing) + +## عرض تتبعاتك + +بعد تشغيل تطبيق CrewAI: + +1. سجل الدخول إلى [لوحة معلومات Maxim](https://app.getmaxim.ai/login) +2. انتقل إلى مستودعك +3. اعرض تتبعات الوكلاء المفصلة، بما في ذلك: + - محادثات الوكلاء + - أنماط استخدام الأدوات + - مقاييس الأداء + - تحليلات التكاليف + + + +## استكشاف الأخطاء وإصلاحها + +### المشاكل الشائعة + +- **عدم ظهور تتبعات**: تأكد من صحة مفتاح API ومعرف المستودع +- تأكد من استدعاء **`instrument_crewai()`** **_قبل_** تشغيل طاقمك +- عيّن `debug=True` في استدعاء `instrument_crewai()` لإظهار أي أخطاء داخلية: + + ```python + instrument_crewai(logger, debug=True) + ``` +- أعدّ وكلاءك مع `verbose=True` لالتقاط سجلات مفصلة +- تحقق مرة أخرى من أن `instrument_crewai()` يُستدعى **قبل** إنشاء أو تنفيذ الوكلاء + +## الموارد + + + + وثائق CrewAI الرسمية + + + وثائق Maxim الرسمية + + + Maxim Github + + diff --git a/docs/ar/observability/mlflow.mdx b/docs/ar/observability/mlflow.mdx new file mode 100644 index 000000000..d8945f14d --- /dev/null +++ b/docs/ar/observability/mlflow.mdx @@ -0,0 +1,206 @@ +--- +title: تكامل MLflow +description: ابدأ بسرعة في مراقبة وكلائك باستخدام MLflow. +icon: bars-staggered +mode: "wide" +--- + +# نظرة عامة على MLflow + +[MLflow](https://mlflow.org/) هو منصة مفتوحة المصدر لمساعدة ممارسي تعلم الآلة والفرق في التعامل مع تعقيدات عملية تعلم الآلة. + +يوفر ميزة التتبع التي تعزز قابلية مراقبة نماذج اللغة الكبيرة (LLM) في تطبيقات الذكاء الاصطناعي التوليدي الخاصة بك من خلال التقاط معلومات تفصيلية حول تنفيذ خدمات تطبيقك. +يوفر التتبع طريقة لتسجيل المدخلات والمخرجات والبيانات الوصفية المرتبطة بكل خطوة وسيطة في الطلب، مما يتيح لك تحديد مصدر الأخطاء والسلوكيات غير المتوقعة بسهولة. + +![نظرة عامة على استخدام تتبع crewAI مع MLflow](/images/mlflow-tracing.gif) + +### الميزات + +- **لوحة معلومات التتبع**: راقب أنشطة وكلاء crewAI الخاصين بك من خلال لوحات معلومات تفصيلية تتضمن المدخلات والمخرجات والبيانات الوصفية للنطاقات. +- **التتبع الآلي**: تكامل مؤتمت بالكامل مع crewAI، يمكن تفعيله عبر تشغيل `mlflow.crewai.autolog()`. +- **أدوات التتبع اليدوي بأقل مجهود**: خصّص أدوات التتبع من خلال واجهات برمجة التطبيقات عالية المستوى من MLflow مثل المزخرفات وأغلفة الدوال ومديري السياق. +- **التوافق مع OpenTelemetry**: يدعم تتبع MLflow تصدير التتبعات إلى جامع OpenTelemetry، الذي يمكن استخدامه بعد ذلك لتصدير التتبعات إلى خلفيات متنوعة مثل Jaeger وZipkin وAWS X-Ray. +- **تغليف ونشر الوكلاء**: قم بتغليف ونشر وكلاء crewAI الخاصين بك إلى خادم استدلال مع مجموعة متنوعة من أهداف النشر. +- **استضافة آمنة لنماذج LLM**: استضف نماذج LLM متعددة من مزودين مختلفين في نقطة نهاية موحدة من خلال بوابة MLflow. +- **التقييم**: قيّم وكلاء crewAI الخاصين بك باستخدام مجموعة واسعة من المقاييس عبر واجهة برمجة تطبيقات مريحة `mlflow.evaluate()`. + +## تعليمات الإعداد + + + + ```shell + # The crewAI integration is available in mlflow>=2.19.0 + pip install mlflow + ``` + + + ```shell + # This process is optional, but it is recommended to use MLflow tracking server for better visualization and broader features. + mlflow server + ``` + + + أضف السطرين التاليين إلى كود تطبيقك: + + ```python + import mlflow + + mlflow.crewai.autolog() + + # Optional: Set a tracking URI and an experiment name if you have a tracking server + mlflow.set_tracking_uri("http://localhost:5000") + mlflow.set_experiment("CrewAI") + ``` + + مثال على الاستخدام لتتبع وكلاء CrewAI: + + ```python + from crewai import Agent, Crew, Task + from crewai.knowledge.source.string_knowledge_source import StringKnowledgeSource + from crewai_tools import SerperDevTool, WebsiteSearchTool + + from textwrap import dedent + + content = "Users name is John. He is 30 years old and lives in San Francisco." + string_source = StringKnowledgeSource( + content=content, metadata={"preference": "personal"} + ) + + search_tool = WebsiteSearchTool() + + + class TripAgents: + def city_selection_agent(self): + return Agent( + role="City Selection Expert", + goal="Select the best city based on weather, season, and prices", + backstory="An expert in analyzing travel data to pick ideal destinations", + tools=[ + search_tool, + ], + verbose=True, + ) + + def local_expert(self): + return Agent( + role="Local Expert at this city", + goal="Provide the BEST insights about the selected city", + backstory="""A knowledgeable local guide with extensive information + about the city, it's attractions and customs""", + tools=[search_tool], + verbose=True, + ) + + + class TripTasks: + def identify_task(self, agent, origin, cities, interests, range): + return Task( + description=dedent( + f""" + Analyze and select the best city for the trip based + on specific criteria such as weather patterns, seasonal + events, and travel costs. This task involves comparing + multiple cities, considering factors like current weather + conditions, upcoming cultural or seasonal events, and + overall travel expenses. + Your final answer must be a detailed + report on the chosen city, and everything you found out + about it, including the actual flight costs, weather + forecast and attractions. + + Traveling from: {origin} + City Options: {cities} + Trip Date: {range} + Traveler Interests: {interests} + """ + ), + agent=agent, + expected_output="Detailed report on the chosen city including flight costs, weather forecast, and attractions", + ) + + def gather_task(self, agent, origin, interests, range): + return Task( + description=dedent( + f""" + As a local expert on this city you must compile an + in-depth guide for someone traveling there and wanting + to have THE BEST trip ever! + Gather information about key attractions, local customs, + special events, and daily activity recommendations. + Find the best spots to go to, the kind of place only a + local would know. + This guide should provide a thorough overview of what + the city has to offer, including hidden gems, cultural + hotspots, must-visit landmarks, weather forecasts, and + high level costs. + The final answer must be a comprehensive city guide, + rich in cultural insights and practical tips, + tailored to enhance the travel experience. + + Trip Date: {range} + Traveling from: {origin} + Traveler Interests: {interests} + """ + ), + agent=agent, + expected_output="Comprehensive city guide including hidden gems, cultural hotspots, and practical travel tips", + ) + + + class TripCrew: + def __init__(self, origin, cities, date_range, interests): + self.cities = cities + self.origin = origin + self.interests = interests + self.date_range = date_range + + def run(self): + agents = TripAgents() + tasks = TripTasks() + + city_selector_agent = agents.city_selection_agent() + local_expert_agent = agents.local_expert() + + identify_task = tasks.identify_task( + city_selector_agent, + self.origin, + self.cities, + self.interests, + self.date_range, + ) + gather_task = tasks.gather_task( + local_expert_agent, self.origin, self.interests, self.date_range + ) + + crew = Crew( + agents=[city_selector_agent, local_expert_agent], + tasks=[identify_task, gather_task], + verbose=True, + memory=True, + knowledge={ + "sources": [string_source], + "metadata": {"preference": "personal"}, + }, + ) + + result = crew.kickoff() + return result + + + trip_crew = TripCrew("California", "Tokyo", "Dec 12 - Dec 20", "sports") + result = trip_crew.run() + + print(result) + ``` + راجع [وثائق تتبع MLflow](https://mlflow.org/docs/latest/llms/tracing/index.html) لمزيد من الإعدادات وحالات الاستخدام. + + + الآن يتم التقاط تتبعات وكلاء crewAI الخاصين بك بواسطة MLflow. + لنقم بزيارة خادم تتبع MLflow لعرض التتبعات والحصول على رؤى حول وكلائك. + + افتح `127.0.0.1:5000` في متصفحك لزيارة خادم تتبع MLflow. + + MLflow tracing example with crewai + + + diff --git a/docs/ar/observability/neatlogs.mdx b/docs/ar/observability/neatlogs.mdx new file mode 100644 index 000000000..7fbc188ad --- /dev/null +++ b/docs/ar/observability/neatlogs.mdx @@ -0,0 +1,134 @@ +--- +title: تكامل Neatlogs +description: افهم وأصلح وشارك عمليات تشغيل وكلاء CrewAI الخاصة بك +icon: magnifying-glass-chart +mode: "wide" +--- + +# مقدمة + +يساعدك Neatlogs على **رؤية ما فعله وكيلك**، و**لماذا**، و**مشاركته**. + +يلتقط كل خطوة: الأفكار، واستدعاءات الأدوات، والاستجابات، والتقييمات. لا سجلات خام. فقط تتبعات واضحة ومنظمة. ممتاز لتصحيح الأخطاء والتعاون. + +## لماذا تستخدم Neatlogs؟ + +يستخدم وكلاء CrewAI أدوات متعددة وخطوات تفكير. عندما يحدث خطأ ما، تحتاج إلى السياق - وليس فقط الأخطاء. + +يتيح لك Neatlogs: + +- تتبع مسار اتخاذ القرار بالكامل +- إضافة ملاحظات مباشرة على الخطوات +- الدردشة مع التتبع باستخدام مساعد الذكاء الاصطناعي +- مشاركة عمليات التشغيل علنياً للحصول على ملاحظات +- تحويل الرؤى إلى مهام + +كل ذلك في مكان واحد. + +إدارة تتبعاتك بسهولة + +![التتبعات](/images/neatlogs-1.png) +![استجابة التتبع](/images/neatlogs-2.png) + +أفضل تجربة مستخدم لعرض تتبع CrewAI. انشر التعليقات أينما تريد. استخدم الذكاء الاصطناعي لتصحيح الأخطاء. + +![تفاصيل التتبع](/images/neatlogs-3.png) +![روبوت الدردشة الذكي مع التتبع](/images/neatlogs-4.png) +![درج التعليقات](/images/neatlogs-5.png) + +## الميزات الأساسية + +- **عارض التتبع**: تتبع الأفكار والأدوات والقرارات بالتسلسل +- **التعليقات المضمنة**: أشر إلى زملاء الفريق على أي خطوة تتبع +- **الملاحظات والتقييم**: حدد المخرجات كصحيحة أو غير صحيحة +- **إبراز الأخطاء**: وسم تلقائي لأخطاء API/الأدوات +- **تحويل المهام**: حوّل التعليقات إلى مهام موكلة +- **اسأل التتبع (AI)**: تحدث مع تتبعك باستخدام روبوت Neatlogs الذكي +- **المشاركة العامة**: انشر روابط التتبع لمجتمعك + +## إعداد سريع مع CrewAI + + + + قم بزيارة [neatlogs.com](https://neatlogs.com/?utm_source=crewAI-docs)، وأنشئ مشروعاً، وانسخ مفتاح API. + + + ```bash + pip install neatlogs + ``` + (أحدث إصدار 0.8.0، Python 3.8+؛ رخصة MIT) + + + قبل بدء وكلاء Crew، أضف: + + ```python + import neatlogs + neatlogs.init("YOUR_PROJECT_API_KEY") + ``` + + يعمل الوكلاء كالمعتاد. يلتقط Neatlogs كل شيء تلقائياً. + + + + + + +## تحت الغطاء + +وفقاً لـ GitHub، فإن Neatlogs: + +- يلتقط الأفكار واستدعاءات الأدوات والاستجابات والأخطاء وإحصائيات الرموز المميزة +- يدعم توليد المهام بالذكاء الاصطناعي وسير عمل التقييم المتين + +كل ذلك بسطرين فقط من الكود. + + + +## شاهده وهو يعمل + +### عرض توضيحي كامل (4 دقائق) + + + +### تكامل CrewAI (30 ثانية) + + + + + +## الروابط والدعم + +- [وثائق Neatlogs](https://docs.neatlogs.com/) +- [لوحة التحكم ومفتاح API](https://app.neatlogs.com/) +- [تابعنا على Twitter](https://twitter.com/neatlogs) +- البريد الإلكتروني: hello@neatlogs.com +- [GitHub SDK](https://github.com/NeatLogs/neatlogs) + + + +## الخلاصة + +بمجرد: + +```bash +pip install neatlogs + +import neatlogs +neatlogs.init("YOUR_API_KEY") + +You can now capture, understand, share, and act on your CrewAI agent runs in seconds. +No setup overhead. Full trace transparency. Full team collaboration. +``` diff --git a/docs/ar/observability/openlit.mdx b/docs/ar/observability/openlit.mdx new file mode 100644 index 000000000..a0aa5533d --- /dev/null +++ b/docs/ar/observability/openlit.mdx @@ -0,0 +1,181 @@ +--- +title: تكامل OpenLIT +description: ابدأ بسرعة في مراقبة وكلائك بسطر واحد فقط من الكود باستخدام OpenTelemetry. +icon: magnifying-glass-chart +mode: "wide" +--- + +# نظرة عامة على OpenLIT + +[OpenLIT](https://github.com/openlit/openlit?src=crewai-docs) هو أداة مفتوحة المصدر تجعل من السهل مراقبة أداء وكلاء الذكاء الاصطناعي ونماذج LLM وقواعد بيانات المتجهات ووحدات GPU بسطر **واحد** فقط من الكود. + +يوفر تتبعاً ومقاييس أصلية لـ OpenTelemetry لتتبع المعلمات المهمة مثل التكلفة وزمن الاستجابة والتفاعلات وتسلسل المهام. +يمكّنك هذا الإعداد من تتبع المعلمات الفائقة ومراقبة مشكلات الأداء، مما يساعدك في إيجاد طرق لتحسين وضبط وكلائك بمرور الوقت. + + + Overview Agent usage including cost and tokens + Overview of agent otel traces and metrics + Overview of agent traces in details + + +### الميزات + +- **لوحة معلومات التحليلات**: راقب صحة وأداء وكلائك من خلال لوحات معلومات تفصيلية تتتبع المقاييس والتكاليف وتفاعلات المستخدمين. +- **SDK مراقبة أصلي لـ OpenTelemetry**: حزم SDK محايدة للمورد لإرسال التتبعات والمقاييس إلى أدوات المراقبة الحالية مثل Grafana وDataDog وغيرها. +- **تتبع التكاليف للنماذج المخصصة والمعدّلة**: خصّص تقديرات التكلفة لنماذج محددة باستخدام ملفات تسعير مخصصة لوضع ميزانية دقيقة. +- **لوحة مراقبة الاستثناءات**: اكتشف وحل المشكلات بسرعة من خلال تتبع الاستثناءات والأخطاء الشائعة بلوحة مراقبة. +- **الامتثال والأمان**: اكتشف التهديدات المحتملة مثل الألفاظ البذيئة وتسريبات المعلومات الشخصية. +- **كشف حقن الموجهات**: حدد حقن الكود المحتمل وتسريبات الأسرار. +- **إدارة مفاتيح API والأسرار**: تعامل مع مفاتيح API لنماذج LLM وأسرارك مركزياً بأمان، مع تجنب الممارسات غير الآمنة. +- **إدارة الموجهات**: أدر وأصدر موجهات الوكلاء باستخدام PromptHub للوصول المتسق والسهل عبر الوكلاء. +- **ساحة تجربة النماذج**: اختبر وقارن نماذج مختلفة لوكلاء CrewAI قبل النشر. + +## تعليمات الإعداد + + + + + + ```shell + git clone git@github.com:openlit/openlit.git + ``` + + + من المجلد الجذري لـ [مستودع OpenLIT](https://github.com/openlit/openlit)، شغّل الأمر التالي: + ```shell + docker compose up -d + ``` + + + + + ```shell + pip install openlit + ``` + + + أضف السطرين التاليين إلى كود تطبيقك: + + + ```python + import openlit + openlit.init(otlp_endpoint="http://127.0.0.1:4318") + ``` + + مثال على الاستخدام لمراقبة وكيل CrewAI: + + ```python + from crewai import Agent, Task, Crew, Process + import openlit + + openlit.init(disable_metrics=True) + # Define your agents + researcher = Agent( + role="Researcher", + goal="Conduct thorough research and analysis on AI and AI agents", + backstory="You're an expert researcher, specialized in technology, software engineering, AI, and startups. You work as a freelancer and are currently researching for a new client.", + allow_delegation=False, + llm='command-r' + ) + + + # Define your task + task = Task( + description="Generate a list of 5 interesting ideas for an article, then write one captivating paragraph for each idea that showcases the potential of a full article on this topic. Return the list of ideas with their paragraphs and your notes.", + expected_output="5 bullet points, each with a paragraph and accompanying notes.", + ) + + # Define the manager agent + manager = Agent( + role="Project Manager", + goal="Efficiently manage the crew and ensure high-quality task completion", + backstory="You're an experienced project manager, skilled in overseeing complex projects and guiding teams to success. Your role is to coordinate the efforts of the crew members, ensuring that each task is completed on time and to the highest standard.", + allow_delegation=True, + llm='command-r' + ) + + # Instantiate your crew with a custom manager + crew = Crew( + agents=[researcher], + tasks=[task], + manager_agent=manager, + process=Process.hierarchical, + ) + + # Start the crew's work + result = crew.kickoff() + + print(result) + ``` + + + + أضف السطرين التاليين إلى كود تطبيقك: + ```python + import openlit + + openlit.init() + ``` + + شغّل الأمر التالي لإعداد نقطة نهاية تصدير OTEL: + ```shell + export OTEL_EXPORTER_OTLP_ENDPOINT = "http://127.0.0.1:4318" + ``` + + مثال على الاستخدام لمراقبة وكيل CrewAI غير متزامن: + + ```python + import asyncio + from crewai import Crew, Agent, Task + import openlit + + openlit.init(otlp_endpoint="http://127.0.0.1:4318") + + # Create an agent with code execution enabled + coding_agent = Agent( + role="Python Data Analyst", + goal="Analyze data and provide insights using Python", + backstory="You are an experienced data analyst with strong Python skills.", + allow_code_execution=True, + llm="command-r" + ) + + # Create a task that requires code execution + data_analysis_task = Task( + description="Analyze the given dataset and calculate the average age of participants. Ages: {ages}", + agent=coding_agent, + expected_output="5 bullet points, each with a paragraph and accompanying notes.", + ) + + # Create a crew and add the task + analysis_crew = Crew( + agents=[coding_agent], + tasks=[data_analysis_task] + ) + + # Async function to kickoff the crew asynchronously + async def async_crew_execution(): + result = await analysis_crew.kickoff_async(inputs={"ages": [25, 30, 35, 40, 45]}) + print("Crew Result:", result) + + # Run the async function + asyncio.run(async_crew_execution()) + ``` + + + راجع [مستودع Python SDK الخاص بـ OpenLIT](https://github.com/openlit/openlit/tree/main/sdk/python) لمزيد من الإعدادات المتقدمة وحالات الاستخدام. + + + مع جمع بيانات مراقبة الوكلاء وإرسالها إلى OpenLIT، الخطوة التالية هي عرض وتحليل هذه البيانات للحصول على رؤى حول أداء وكيلك وسلوكه وتحديد مجالات التحسين. + + ما عليك سوى التوجه إلى OpenLIT على `127.0.0.1:3000` في متصفحك لبدء الاستكشاف. يمكنك تسجيل الدخول باستخدام بيانات الاعتماد الافتراضية + - **البريد الإلكتروني**: `user@openlit.io` + - **كلمة المرور**: `openlituser` + + + Overview Agent usage including cost and tokens + Overview of agent otel traces and metrics + + + + diff --git a/docs/ar/observability/opik.mdx b/docs/ar/observability/opik.mdx new file mode 100644 index 000000000..60442fe47 --- /dev/null +++ b/docs/ar/observability/opik.mdx @@ -0,0 +1,130 @@ +--- +title: تكامل Opik +description: تعرّف على كيفية استخدام Comet Opik لتصحيح الأخطاء وتقييم ومراقبة تطبيقات CrewAI الخاصة بك مع تتبع شامل وتقييمات آلية ولوحات معلومات جاهزة للإنتاج. +icon: meteor +mode: "wide" +--- + +# نظرة عامة على Opik + +مع [Comet Opik](https://www.comet.com/docs/opik/)، يمكنك تصحيح الأخطاء وتقييم ومراقبة تطبيقات LLM وأنظمة RAG وسير العمل الوكيلي مع تتبع شامل وتقييمات آلية ولوحات معلومات جاهزة للإنتاج. + + + Opik agent monitoring example with CrewAI + + +يوفر Opik دعماً شاملاً لكل مرحلة من مراحل تطوير تطبيق CrewAI الخاص بك: + +- **تسجيل التتبعات والنطاقات**: تتبع تلقائي لاستدعاءات LLM ومنطق التطبيق لتصحيح الأخطاء وتحليل أنظمة التطوير والإنتاج. أضف التعليقات التوضيحية يدوياً أو برمجياً، واعرض وقارن الاستجابات عبر المشاريع. +- **تقييم أداء تطبيق LLM**: قيّم وفقاً لمجموعة اختبار مخصصة وشغّل مقاييس تقييم مدمجة أو حدد مقاييسك الخاصة في SDK أو واجهة المستخدم. +- **الاختبار ضمن خط أنابيب CI/CD**: أنشئ خطوط أساس أداء موثوقة مع اختبارات وحدة LLM من Opik، المبنية على PyTest. شغّل تقييمات عبر الإنترنت للمراقبة المستمرة في الإنتاج. +- **مراقبة وتحليل بيانات الإنتاج**: افهم أداء نماذجك على بيانات غير مرئية في الإنتاج وأنشئ مجموعات بيانات لتكرارات التطوير الجديدة. + +## الإعداد +يوفر Comet نسخة مستضافة من منصة Opik، أو يمكنك تشغيل المنصة محلياً. + +لاستخدام النسخة المستضافة، ما عليك سوى [إنشاء حساب Comet مجاني](https://www.comet.com/signup?utm_medium=github&utm_source=crewai_docs) والحصول على مفتاح API الخاص بك. + +لتشغيل منصة Opik محلياً، راجع [دليل التثبيت](https://www.comet.com/docs/opik/self-host/overview/) لمزيد من المعلومات. + +في هذا الدليل سنستخدم مثال البدء السريع الخاص بـ CrewAI. + + + + ```shell + pip install crewai crewai-tools opik --upgrade + ``` + + + ```python + import opik + opik.configure(use_local=False) + ``` + + + أولاً، نقوم بإعداد مفاتيح API لمزود LLM كمتغيرات بيئة: + + ```python + import os + import getpass + + if "OPENAI_API_KEY" not in os.environ: + os.environ["OPENAI_API_KEY"] = getpass.getpass("Enter your OpenAI API key: ") + ``` + + + الخطوة الأولى هي إنشاء مشروعنا. سنستخدم مثالاً من وثائق CrewAI: + + ```python + from crewai import Agent, Crew, Task, Process + + + class YourCrewName: + def agent_one(self) -> Agent: + return Agent( + role="Data Analyst", + goal="Analyze data trends in the market", + backstory="An experienced data analyst with a background in economics", + verbose=True, + ) + + def agent_two(self) -> Agent: + return Agent( + role="Market Researcher", + goal="Gather information on market dynamics", + backstory="A diligent researcher with a keen eye for detail", + verbose=True, + ) + + def task_one(self) -> Task: + return Task( + name="Collect Data Task", + description="Collect recent market data and identify trends.", + expected_output="A report summarizing key trends in the market.", + agent=self.agent_one(), + ) + + def task_two(self) -> Task: + return Task( + name="Market Research Task", + description="Research factors affecting market dynamics.", + expected_output="An analysis of factors influencing the market.", + agent=self.agent_two(), + ) + + def crew(self) -> Crew: + return Crew( + agents=[self.agent_one(), self.agent_two()], + tasks=[self.task_one(), self.task_two()], + process=Process.sequential, + verbose=True, + ) + + ``` + + الآن يمكننا استيراد متتبع Opik وتشغيل الطاقم: + + ```python + from opik.integrations.crewai import track_crewai + + track_crewai(project_name="crewai-integration-demo") + + my_crew = YourCrewName().crew() + result = my_crew.kickoff() + + print(result) + ``` + بعد تشغيل تطبيق CrewAI، قم بزيارة تطبيق Opik لعرض: + - تتبعات LLM والنطاقات وبياناتها الوصفية + - تفاعلات الوكلاء وتدفق تنفيذ المهام + - مقاييس الأداء مثل زمن الاستجابة واستخدام الرموز المميزة + - مقاييس التقييم (مدمجة أو مخصصة) + + + +## الموارد + +- [وثائق Opik](https://www.comet.com/docs/opik/) +- [Opik + CrewAI Colab](https://colab.research.google.com/github/comet-ml/opik/blob/main/apps/opik-documentation/documentation/docs/cookbook/crewai.ipynb) +- [X](https://x.com/cometml) +- [Slack](https://slack.comet.com/) diff --git a/docs/ar/observability/overview.mdx b/docs/ar/observability/overview.mdx new file mode 100644 index 000000000..9e6e239c7 --- /dev/null +++ b/docs/ar/observability/overview.mdx @@ -0,0 +1,120 @@ +--- +title: "نظرة عامة" +description: "راقب وقيّم وحسّن وكلاء CrewAI الخاصين بك باستخدام أدوات مراقبة شاملة" +icon: "face-smile" +mode: "wide" +--- + +## المراقبة في CrewAI + +تعد المراقبة أمراً بالغ الأهمية لفهم كيفية أداء وكلاء CrewAI، وتحديد الاختناقات، وضمان التشغيل الموثوق في بيئات الإنتاج. يغطي هذا القسم مختلف الأدوات والمنصات التي توفر إمكانيات المراقبة والتقييم والتحسين لسير عمل وكلائك. + +## لماذا تعد المراقبة مهمة + +- **مراقبة الأداء**: تتبع أوقات تنفيذ الوكلاء واستخدام الرموز المميزة واستهلاك الموارد +- **ضمان الجودة**: تقييم جودة المخرجات واتساقها عبر سيناريوهات مختلفة +- **تصحيح الأخطاء**: تحديد وحل المشكلات في سلوك الوكلاء وتنفيذ المهام +- **إدارة التكاليف**: مراقبة استخدام API لنماذج LLM والتكاليف المرتبطة بها +- **التحسين المستمر**: جمع الرؤى لتحسين أداء الوكلاء بمرور الوقت + +## أدوات المراقبة المتاحة + +### منصات المراقبة والتتبع + + + + + تتبع شامل لسير عمل CrewAI مع التقاط تلقائي لتفاعلات الوكلاء. + + + + مراقبة أصلية لـ OpenTelemetry مع تتبع التكاليف وتحليلات الأداء. + + + + إدارة دورة حياة تعلم الآلة مع إمكانيات التتبع والتقييم. + + + + منصة هندسة LLM مع تتبع وتحليلات تفصيلية. + + + + مراقبة مفتوحة المصدر لنماذج LLM وأطر العمل الوكيلية. + + + + منصة مراقبة الذكاء الاصطناعي للمراقبة واستكشاف الأخطاء وإصلاحها. + + + + بوابة ذكاء اصطناعي مع مراقبة شاملة وميزات موثوقية. + + + + تصحيح الأخطاء وتقييم ومراقبة تطبيقات LLM مع تتبع شامل. + + + + منصة Weights & Biases لتتبع وتقييم تطبيقات الذكاء الاصطناعي. + + + +### التقييم وضمان الجودة + + + + منصة تقييم شاملة لمخرجات LLM وسلوكيات الوكلاء. + + + +## مقاييس المراقبة الرئيسية + +### مقاييس الأداء +- **وقت التنفيذ**: المدة التي يستغرقها الوكلاء لإكمال المهام +- **استخدام الرموز المميزة**: الرموز المدخلة/المخرجة المستهلكة من استدعاءات LLM +- **زمن استجابة API**: أوقات الاستجابة من الخدمات الخارجية +- **معدل النجاح**: نسبة المهام المكتملة بنجاح + +### مقاييس الجودة +- **دقة المخرجات**: صحة استجابات الوكلاء +- **الاتساق**: الموثوقية عبر مدخلات متشابهة +- **الصلة**: مدى تطابق المخرجات مع النتائج المتوقعة +- **السلامة**: الامتثال لسياسات المحتوى والإرشادات + +### مقاييس التكلفة +- **تكاليف API**: النفقات من استخدام مزودي LLM +- **استخدام الموارد**: استهلاك الحوسبة والذاكرة +- **التكلفة لكل مهمة**: الكفاءة الاقتصادية لعمليات الوكلاء +- **تتبع الميزانية**: المراقبة مقابل حدود الإنفاق + +## البدء + +1. **اختر أدواتك**: حدد منصات المراقبة التي تتوافق مع احتياجاتك +2. **أضف الأدوات لكودك**: أضف المراقبة لتطبيقات CrewAI الخاصة بك +3. **أعدّ لوحات المعلومات**: هيئ العروض المرئية للمقاييس الرئيسية +4. **حدد التنبيهات**: أنشئ إشعارات للأحداث المهمة +5. **أنشئ خطوط الأساس**: قس الأداء الأولي للمقارنة +6. **كرر وحسّن**: استخدم الرؤى لتحسين وكلائك + +## أفضل الممارسات + +### مرحلة التطوير +- استخدم التتبع التفصيلي لفهم سلوك الوكلاء +- طبّق مقاييس التقييم مبكراً في التطوير +- راقب استخدام الموارد أثناء الاختبار +- أعدّ فحوصات جودة آلية + +### مرحلة الإنتاج +- طبّق مراقبة وتنبيهات شاملة +- تتبع اتجاهات الأداء بمرور الوقت +- راقب الشذوذ والتدهور +- حافظ على رؤية التكاليف والتحكم بها + +### التحسين المستمر +- مراجعات أداء وتحسين منتظمة +- اختبار A/B لتكوينات وكلاء مختلفة +- حلقات تغذية راجعة لتحسين الجودة +- توثيق الدروس المستفادة + +اختر أدوات المراقبة التي تناسب حالة الاستخدام والبنية التحتية ومتطلبات المراقبة الخاصة بك لضمان أن وكلاء CrewAI يعملون بشكل موثوق وفعال. diff --git a/docs/ar/observability/patronus-evaluation.mdx b/docs/ar/observability/patronus-evaluation.mdx new file mode 100644 index 000000000..c6b522640 --- /dev/null +++ b/docs/ar/observability/patronus-evaluation.mdx @@ -0,0 +1,206 @@ +--- +title: تقييم Patronus AI +description: راقب وقيّم أداء وكلاء CrewAI باستخدام منصة التقييم الشاملة من Patronus AI لمخرجات LLM وسلوكيات الوكلاء. +icon: shield-check +mode: "wide" +--- + +# تقييم Patronus AI + +## نظرة عامة + +يوفر [Patronus AI](https://patronus.ai) إمكانيات تقييم ومراقبة شاملة لوكلاء CrewAI، مما يمكّنك من تقييم مخرجات النماذج وسلوكيات الوكلاء والأداء العام للنظام. يتيح لك هذا التكامل تنفيذ سير عمل تقييم مستمر يساعد في الحفاظ على الجودة والموثوقية في بيئات الإنتاج. + +## الميزات الرئيسية + +- **التقييم الآلي**: تقييم فوري لمخرجات وسلوكيات الوكلاء +- **معايير مخصصة**: حدد معايير تقييم محددة مصممة لحالات الاستخدام الخاصة بك +- **مراقبة الأداء**: تتبع مقاييس أداء الوكلاء بمرور الوقت +- **ضمان الجودة**: ضمان جودة مخرجات متسقة عبر سيناريوهات مختلفة +- **السلامة والامتثال**: مراقبة المشكلات المحتملة وانتهاكات السياسات + +## أدوات التقييم + +يوفر Patronus ثلاث أدوات تقييم رئيسية لحالات استخدام مختلفة: + +1. **PatronusEvalTool**: يسمح للوكلاء باختيار المقيّم والمعايير الأنسب لمهمة التقييم. +2. **PatronusPredefinedCriteriaEvalTool**: يستخدم مقيّماً ومعايير محددة مسبقاً من قبل المستخدم. +3. **PatronusLocalEvaluatorTool**: يستخدم دوال تقييم مخصصة محددة من قبل المستخدم. + +## التثبيت + +لاستخدام هذه الأدوات، تحتاج إلى تثبيت حزمة Patronus: + +```shell +uv add patronus +``` + +ستحتاج أيضاً إلى إعداد مفتاح API الخاص بـ Patronus كمتغير بيئة: + +```shell +export PATRONUS_API_KEY="your_patronus_api_key" +``` + +## خطوات البدء + +لاستخدام أدوات تقييم Patronus بفعالية، اتبع الخطوات التالية: + +1. **تثبيت Patronus**: ثبّت حزمة Patronus باستخدام الأمر أعلاه. +2. **إعداد مفتاح API**: عيّن مفتاح API الخاص بـ Patronus كمتغير بيئة. +3. **اختيار الأداة المناسبة**: حدد أداة تقييم Patronus المناسبة بناءً على احتياجاتك. +4. **إعداد الأداة**: هيئ الأداة بالمعاملات اللازمة. + +## أمثلة + +### استخدام PatronusEvalTool + +يوضح المثال التالي كيفية استخدام `PatronusEvalTool`، التي تسمح للوكلاء باختيار المقيّم والمعايير الأنسب: + +```python Code +from crewai import Agent, Task, Crew +from crewai_tools import PatronusEvalTool + +# Initialize the tool +patronus_eval_tool = PatronusEvalTool() + +# Define an agent that uses the tool +coding_agent = Agent( + role="Coding Agent", + goal="Generate high quality code and verify that the output is code", + backstory="An experienced coder who can generate high quality python code.", + tools=[patronus_eval_tool], + verbose=True, +) + +# Example task to generate and evaluate code +generate_code_task = Task( + description="Create a simple program to generate the first N numbers in the Fibonacci sequence. Select the most appropriate evaluator and criteria for evaluating your output.", + expected_output="Program that generates the first N numbers in the Fibonacci sequence.", + agent=coding_agent, +) + +# Create and run the crew +crew = Crew(agents=[coding_agent], tasks=[generate_code_task]) +result = crew.kickoff() +``` + +### استخدام PatronusPredefinedCriteriaEvalTool + +يوضح المثال التالي كيفية استخدام `PatronusPredefinedCriteriaEvalTool`، التي تستخدم مقيّماً ومعايير محددة مسبقاً: + +```python Code +from crewai import Agent, Task, Crew +from crewai_tools import PatronusPredefinedCriteriaEvalTool + +# Initialize the tool with predefined criteria +patronus_eval_tool = PatronusPredefinedCriteriaEvalTool( + evaluators=[{"evaluator": "judge", "criteria": "contains-code"}] +) + +# Define an agent that uses the tool +coding_agent = Agent( + role="Coding Agent", + goal="Generate high quality code", + backstory="An experienced coder who can generate high quality python code.", + tools=[patronus_eval_tool], + verbose=True, +) + +# Example task to generate code +generate_code_task = Task( + description="Create a simple program to generate the first N numbers in the Fibonacci sequence.", + expected_output="Program that generates the first N numbers in the Fibonacci sequence.", + agent=coding_agent, +) + +# Create and run the crew +crew = Crew(agents=[coding_agent], tasks=[generate_code_task]) +result = crew.kickoff() +``` + +### استخدام PatronusLocalEvaluatorTool + +يوضح المثال التالي كيفية استخدام `PatronusLocalEvaluatorTool`، التي تستخدم دوال تقييم مخصصة: + +```python Code +from crewai import Agent, Task, Crew +from crewai_tools import PatronusLocalEvaluatorTool +from patronus import Client, EvaluationResult +import random + +# Initialize the Patronus client +client = Client() + +# Register a custom evaluator +@client.register_local_evaluator("random_evaluator") +def random_evaluator(**kwargs): + score = random.random() + return EvaluationResult( + score_raw=score, + pass_=score >= 0.5, + explanation="example explanation", + ) + +# Initialize the tool with the custom evaluator +patronus_eval_tool = PatronusLocalEvaluatorTool( + patronus_client=client, + evaluator="random_evaluator", + evaluated_model_gold_answer="example label", +) + +# Define an agent that uses the tool +coding_agent = Agent( + role="Coding Agent", + goal="Generate high quality code", + backstory="An experienced coder who can generate high quality python code.", + tools=[patronus_eval_tool], + verbose=True, +) + +# Example task to generate code +generate_code_task = Task( + description="Create a simple program to generate the first N numbers in the Fibonacci sequence.", + expected_output="Program that generates the first N numbers in the Fibonacci sequence.", + agent=coding_agent, +) + +# Create and run the crew +crew = Crew(agents=[coding_agent], tasks=[generate_code_task]) +result = crew.kickoff() +``` + +## المعاملات + +### PatronusEvalTool + +لا تتطلب `PatronusEvalTool` أي معاملات أثناء التهيئة. تقوم تلقائياً بجلب المقيّمين والمعايير المتاحة من API الخاص بـ Patronus. + +### PatronusPredefinedCriteriaEvalTool + +تقبل `PatronusPredefinedCriteriaEvalTool` المعاملات التالية أثناء التهيئة: + +- **evaluators**: مطلوب. قائمة من القواميس تحتوي على المقيّم والمعايير المراد استخدامها. مثال: `[{"evaluator": "judge", "criteria": "contains-code"}]`. + +### PatronusLocalEvaluatorTool + +تقبل `PatronusLocalEvaluatorTool` المعاملات التالية أثناء التهيئة: + +- **patronus_client**: مطلوب. مثيل عميل Patronus. +- **evaluator**: اختياري. اسم المقيّم المحلي المسجل للاستخدام. القيمة الافتراضية هي سلسلة نصية فارغة. +- **evaluated_model_gold_answer**: اختياري. الإجابة المرجعية للاستخدام في التقييم. القيمة الافتراضية هي سلسلة نصية فارغة. + +## الاستخدام + +عند استخدام أدوات تقييم Patronus، تقدم مدخلات النموذج ومخرجاته وسياقه، وتعيد الأداة نتائج التقييم من API الخاص بـ Patronus. + +بالنسبة لـ `PatronusEvalTool` و`PatronusPredefinedCriteriaEvalTool`، المعاملات التالية مطلوبة عند استدعاء الأداة: + +- **evaluated_model_input**: وصف مهمة الوكيل بنص بسيط. +- **evaluated_model_output**: مخرجات الوكيل للمهمة. +- **evaluated_model_retrieved_context**: سياق الوكيل. + +بالنسبة لـ `PatronusLocalEvaluatorTool`، نفس المعاملات مطلوبة، لكن المقيّم والإجابة المرجعية يتم تحديدهما أثناء التهيئة. + +## الخلاصة + +توفر أدوات تقييم Patronus طريقة قوية لتقييم وتسجيل درجات مدخلات ومخرجات النماذج باستخدام منصة Patronus AI. من خلال تمكين الوكلاء من تقييم مخرجاتهم أو مخرجات وكلاء آخرين، يمكن لهذه الأدوات المساعدة في تحسين جودة وموثوقية سير عمل CrewAI. diff --git a/docs/ar/observability/portkey.mdx b/docs/ar/observability/portkey.mdx new file mode 100644 index 000000000..e676b7a35 --- /dev/null +++ b/docs/ar/observability/portkey.mdx @@ -0,0 +1,823 @@ +--- +title: تكامل Portkey +description: كيفية استخدام Portkey مع CrewAI +icon: key +mode: "wide" +--- + +Portkey CrewAI Header Image + + + +## مقدمة + +يعزز Portkey إمكانيات CrewAI بميزات جاهزة للإنتاج، محولاً طواقم الوكلاء التجريبية إلى أنظمة متينة من خلال توفير: + +- **مراقبة كاملة** لكل خطوة وكيل واستخدام أداة وتفاعل +- **موثوقية مدمجة** مع آليات الاحتياط وإعادة المحاولة وموازنة الأحمال +- **تتبع التكاليف وتحسينها** لإدارة إنفاقك على الذكاء الاصطناعي +- **الوصول إلى أكثر من 200 نموذج LLM** من خلال تكامل واحد +- **حواجز الحماية** للحفاظ على سلوك الوكلاء آمناً ومتوافقاً +- **موجهات مُتحكم بإصداراتها** لأداء وكلاء متسق + + +### التثبيت والإعداد + + + +```bash +pip install -U crewai portkey-ai +``` + + + +أنشئ مفتاح API لـ Portkey مع حدود ميزانية/معدل اختيارية من [لوحة تحكم Portkey](https://app.portkey.ai/). يمكنك أيضاً إرفاق إعدادات للموثوقية والتخزين المؤقت والمزيد لهذا المفتاح. المزيد عن هذا لاحقاً. + + + +التكامل بسيط - ما عليك سوى تحديث إعداد LLM في تكوين CrewAI الخاص بك: + +```python +from crewai import LLM +from portkey_ai import createHeaders, PORTKEY_GATEWAY_URL + +# Create an LLM instance with Portkey integration +gpt_llm = LLM( + model="gpt-4o", + base_url=PORTKEY_GATEWAY_URL, + api_key="dummy", # We are using a Virtual key, so this is a placeholder + extra_headers=createHeaders( + api_key="YOUR_PORTKEY_API_KEY", + virtual_key="YOUR_LLM_VIRTUAL_KEY", + trace_id="unique-trace-id", # Optional, for request tracing + ) +) + +#Use them in your Crew Agents like this: + + @agent + def lead_market_analyst(self) -> Agent: + return Agent( + config=self.agents_config['lead_market_analyst'], + verbose=True, + memory=False, + llm=gpt_llm + ) + +``` + + +**ما هي المفاتيح الافتراضية؟** تخزّن المفاتيح الافتراضية في Portkey مفاتيح API لمزودي LLM (OpenAI وAnthropic وغيرها) بشكل آمن في خزنة مشفرة. تتيح تدوير المفاتيح وإدارة الميزانية بسهولة. [تعرّف على المزيد حول المفاتيح الافتراضية هنا](https://portkey.ai/docs/product/ai-gateway/virtual-keys). + + + + +## ميزات الإنتاج + +### 1. مراقبة محسّنة + +يوفر Portkey مراقبة شاملة لوكلاء CrewAI، مما يساعدك على فهم ما يحدث بالضبط أثناء كل عملية تنفيذ. + + + + + + + +توفر التتبعات عرضاً هرمياً لتنفيذ طاقمك، يظهر تسلسل استدعاءات LLM واستدعاءات الأدوات وانتقالات الحالة. + +```python +# Add trace_id to enable hierarchical tracing in Portkey +portkey_llm = LLM( + model="gpt-4o", + base_url=PORTKEY_GATEWAY_URL, + api_key="dummy", + extra_headers=createHeaders( + api_key="YOUR_PORTKEY_API_KEY", + virtual_key="YOUR_OPENAI_VIRTUAL_KEY", + trace_id="unique-session-id" # Add unique trace ID + ) +) +``` + + + + + + + +يسجّل Portkey كل تفاعل مع نماذج LLM، بما في ذلك: + +- حمولات الطلب والاستجابة الكاملة +- مقاييس زمن الاستجابة واستخدام الرموز المميزة +- حسابات التكلفة +- استدعاءات الأدوات وتنفيذ الدوال + +يمكن تصفية جميع السجلات حسب البيانات الوصفية ومعرّفات التتبع والنماذج والمزيد، مما يسهّل تصحيح أخطاء عمليات تشغيل طاقم محددة. + + + + + + + +يوفر Portkey لوحات معلومات مدمجة تساعدك على: + +- تتبع التكلفة واستخدام الرموز المميزة عبر جميع عمليات تشغيل الطاقم +- تحليل مقاييس الأداء مثل زمن الاستجابة ومعدلات النجاح +- تحديد الاختناقات في سير عمل الوكلاء +- مقارنة تكوينات الطاقم ونماذج LLM المختلفة + +يمكنك تصفية وتقسيم جميع المقاييس حسب بيانات وصفية مخصصة لتحليل أنواع طواقم أو مجموعات مستخدمين أو حالات استخدام محددة. + + + + + Analytics with metadata filters + + +أضف بيانات وصفية مخصصة لتكوين LLM في CrewAI لتمكين تصفية وتقسيم قوية: + +```python +portkey_llm = LLM( + model="gpt-4o", + base_url=PORTKEY_GATEWAY_URL, + api_key="dummy", + extra_headers=createHeaders( + api_key="YOUR_PORTKEY_API_KEY", + virtual_key="YOUR_OPENAI_VIRTUAL_KEY", + metadata={ + "crew_type": "research_crew", + "environment": "production", + "_user": "user_123", # Special _user field for user analytics + "request_source": "mobile_app" + } + ) +) +``` + +يمكن استخدام هذه البيانات الوصفية لتصفية السجلات والتتبعات والمقاييس في لوحة تحكم Portkey، مما يتيح لك تحليل عمليات تشغيل طاقم أو مستخدمين أو بيئات محددة. + + + +### 2. الموثوقية - حافظ على تشغيل طواقمك بسلاسة + +عند تشغيل الطواقم في الإنتاج، قد تحدث مشكلات - حدود معدل API أو مشكلات الشبكة أو انقطاعات المزود. تضمن ميزات الموثوقية في Portkey استمرار عمل وكلائك بسلاسة حتى عند حدوث مشكلات. + +من السهل تفعيل الاحتياط في إعداد CrewAI الخاص بك باستخدام تكوين Portkey: + +```python +from crewai import LLM +from portkey_ai import createHeaders, PORTKEY_GATEWAY_URL + +# Create LLM with fallback configuration +portkey_llm = LLM( + model="gpt-4o", + max_tokens=1000, + base_url=PORTKEY_GATEWAY_URL, + api_key="dummy", + extra_headers=createHeaders( + api_key="YOUR_PORTKEY_API_KEY", + config={ + "strategy": { + "mode": "fallback" + }, + "targets": [ + { + "provider": "openai", + "api_key": "YOUR_OPENAI_API_KEY", + "override_params": {"model": "gpt-4o"} + }, + { + "provider": "anthropic", + "api_key": "YOUR_ANTHROPIC_API_KEY", + "override_params": {"model": "claude-3-opus-20240229"} + } + ] + } + ) +) + +# Use this LLM configuration with your agents +``` + +سيحاول هذا التكوين تلقائياً استخدام Claude إذا فشل طلب GPT-4o، مما يضمن استمرار تشغيل طاقمك. + + + + يتعامل مع حالات الفشل المؤقتة تلقائياً. إذا فشل استدعاء LLM، سيعيد Portkey محاولة نفس الطلب لعدد محدد من المرات - مثالي لحدود المعدل أو انقطاعات الشبكة. + + + امنع وكلاءك من التعليق. عيّن مهلات لضمان حصولك على استجابات (أو الفشل بأمان) ضمن الأطر الزمنية المطلوبة. + + + أرسل طلبات مختلفة إلى مزودين مختلفين. وجّه التفكير المعقد إلى GPT-4 والمهام الإبداعية إلى Claude والاستجابات السريعة إلى Gemini بناءً على احتياجاتك. + + + استمر في العمل حتى لو فشل مزودك الأساسي. انتقل تلقائياً إلى مزودين احتياطيين للحفاظ على التوفر. + + + وزّع الطلبات عبر مفاتيح API أو مزودين متعددين. ممتاز لعمليات الطاقم عالية الحجم والبقاء ضمن حدود المعدل. + + + +### 3. إدارة الموجهات في CrewAI + +يساعدك استوديو هندسة الموجهات من Portkey في إنشاء وإدارة وتحسين الموجهات المستخدمة في وكلاء CrewAI. بدلاً من ترميز الموجهات أو التعليمات بشكل ثابت، استخدم API عرض الموجهات من Portkey لجلب وتطبيق موجهاتك المُصدَرة ديناميكياً. + + +![Prompt Playground Interface](https://raw.githubusercontent.com/siddharthsambharia-portkey/Portkey-Product-Images/refs/heads/main/CrewAI%20Portkey%20Docs.webp) + + + + +ساحة تجربة الموجهات هي مكان لمقارنة واختبار ونشر الموجهات المثالية لتطبيق الذكاء الاصطناعي الخاص بك. هي المكان الذي تجرّب فيه نماذج مختلفة وتختبر المتغيرات وتقارن المخرجات وتحسّن استراتيجية هندسة الموجهات قبل النشر في الإنتاج. تتيح لك: + +1. تطوير الموجهات بشكل تكراري قبل استخدامها في وكلائك +2. اختبار الموجهات مع متغيرات ونماذج مختلفة +3. مقارنة المخرجات بين إصدارات موجهات مختلفة +4. التعاون مع أعضاء الفريق في تطوير الموجهات + +تجعل هذه البيئة المرئية من الأسهل صياغة موجهات فعالة لكل خطوة في سير عمل وكلاء CrewAI. + + + +يسترجع API عرض الموجهات قوالب الموجهات الخاصة بك مع جميع المعاملات المُعدّة: + +```python +from crewai import Agent, LLM +from portkey_ai import createHeaders, PORTKEY_GATEWAY_URL, Portkey + +# Initialize Portkey admin client +portkey_admin = Portkey(api_key="YOUR_PORTKEY_API_KEY") + +# Retrieve prompt using the render API +prompt_data = portkey_client.prompts.render( + prompt_id="YOUR_PROMPT_ID", + variables={ + "agent_role": "Senior Research Scientist", + } +) + +backstory_agent_prompt=prompt_data.data.messages[0]["content"] + + +# Set up LLM with Portkey integration +portkey_llm = LLM( + model="gpt-4o", + base_url=PORTKEY_GATEWAY_URL, + api_key="dummy", + extra_headers=createHeaders( + api_key="YOUR_PORTKEY_API_KEY", + virtual_key="YOUR_OPENAI_VIRTUAL_KEY" + ) +) + +# Create agent using the rendered prompt +researcher = Agent( + role="Senior Research Scientist", + goal="Discover groundbreaking insights about the assigned topic", + backstory=backstory_agent, # Use the rendered prompt + verbose=True, + llm=portkey_llm +) +``` + + + +يمكنك: +- إنشاء إصدارات متعددة من نفس الموجه +- مقارنة الأداء بين الإصدارات +- الرجوع إلى إصدارات سابقة عند الحاجة +- تحديد الإصدار المراد استخدامه في كودك: + +```python +# Use a specific prompt version +prompt_data = portkey_admin.prompts.render( + prompt_id="YOUR_PROMPT_ID@version_number", + variables={ + "agent_role": "Senior Research Scientist", + "agent_goal": "Discover groundbreaking insights" + } +) +``` + + + +تستخدم موجهات Portkey قوالب بنمط Mustache لاستبدال المتغيرات بسهولة: + +``` +You are a {{agent_role}} with expertise in {{domain}}. + +Your mission is to {{agent_goal}} by leveraging your knowledge +and experience in the field. + +Always maintain a {{tone}} tone and focus on providing {{focus_area}}. +``` + +عند العرض، ما عليك سوى تمرير المتغيرات: + +```python +prompt_data = portkey_admin.prompts.render( + prompt_id="YOUR_PROMPT_ID", + variables={ + "agent_role": "Senior Research Scientist", + "domain": "artificial intelligence", + "agent_goal": "discover groundbreaking insights", + "tone": "professional", + "focus_area": "practical applications" + } +) +``` + + + + + تعرّف على المزيد حول ميزات إدارة الموجهات في Portkey + + +### 4. حواجز الحماية لطواقم آمنة + +تضمن حواجز الحماية أن وكلاء CrewAI يعملون بأمان ويستجيبون بشكل مناسب في جميع الحالات. + +**لماذا تستخدم حواجز الحماية؟** + +قد يواجه وكلاء CrewAI أوضاع فشل مختلفة: +- توليد محتوى ضار أو غير مناسب +- تسريب معلومات حساسة مثل المعلومات الشخصية +- توهم معلومات غير صحيحة +- توليد مخرجات بتنسيقات غير صحيحة + +تضيف حواجز حماية Portkey حماية لكل من المدخلات والمخرجات. + +**تطبيق حواجز الحماية** + +```python +from crewai import Agent, LLM +from portkey_ai import createHeaders, PORTKEY_GATEWAY_URL + +# Create LLM with guardrails +portkey_llm = LLM( + model="gpt-4o", + base_url=PORTKEY_GATEWAY_URL, + api_key="dummy", + extra_headers=createHeaders( + api_key="YOUR_PORTKEY_API_KEY", + virtual_key="YOUR_OPENAI_VIRTUAL_KEY", + config={ + "input_guardrails": ["guardrails-id-xxx", "guardrails-id-yyy"], + "output_guardrails": ["guardrails-id-zzz"] + } + ) +) + +# Create agent with guardrailed LLM +researcher = Agent( + role="Senior Research Scientist", + goal="Discover groundbreaking insights about the assigned topic", + backstory="You are an expert researcher with deep domain knowledge.", + verbose=True, + llm=portkey_llm +) +``` + +يمكن لحواجز حماية Portkey: +- كشف وحذف المعلومات الشخصية في المدخلات والمخرجات +- تصفية المحتوى الضار أو غير المناسب +- التحقق من تنسيقات الاستجابة وفقاً للمخططات +- التحقق من التوهمات مقابل الحقائق المرجعية +- تطبيق منطق الأعمال والقواعد المخصصة + + + استكشف ميزات حواجز الحماية في Portkey لتعزيز سلامة الوكلاء + + +### 5. تتبع المستخدمين باستخدام البيانات الوصفية + +تتبع المستخدمين الفرديين عبر وكلاء CrewAI باستخدام نظام البيانات الوصفية في Portkey. + +**ما هي البيانات الوصفية في Portkey؟** + +تتيح لك البيانات الوصفية ربط بيانات مخصصة بكل طلب، مما يمكّن التصفية والتقسيم والتحليلات. الحقل الخاص `_user` مصمم خصيصاً لتتبع المستخدمين. + +```python +from crewai import Agent, LLM +from portkey_ai import createHeaders, PORTKEY_GATEWAY_URL + +# Configure LLM with user tracking +portkey_llm = LLM( + model="gpt-4o", + base_url=PORTKEY_GATEWAY_URL, + api_key="dummy", + extra_headers=createHeaders( + api_key="YOUR_PORTKEY_API_KEY", + virtual_key="YOUR_OPENAI_VIRTUAL_KEY", + metadata={ + "_user": "user_123", # Special _user field for user analytics + "user_tier": "premium", + "user_company": "Acme Corp", + "session_id": "abc-123" + } + ) +) + +# Create agent with tracked LLM +researcher = Agent( + role="Senior Research Scientist", + goal="Discover groundbreaking insights about the assigned topic", + backstory="You are an expert researcher with deep domain knowledge.", + verbose=True, + llm=portkey_llm +) +``` + +**تصفية التحليلات حسب المستخدم** + +مع وجود البيانات الوصفية، يمكنك تصفية التحليلات حسب المستخدم وتحليل مقاييس الأداء على أساس كل مستخدم: + + + + + +يمكّن هذا: +- تتبع التكاليف والميزانية لكل مستخدم +- تحليلات مستخدم مخصصة +- مقاييس على مستوى الفريق أو المؤسسة +- مراقبة خاصة بالبيئة (التجريب مقابل الإنتاج) + + + استكشف كيفية استخدام البيانات الوصفية المخصصة لتعزيز تحليلاتك + + +### 6. التخزين المؤقت لطواقم فعالة + +طبّق التخزين المؤقت لجعل وكلاء CrewAI أكثر كفاءة وفعالية من حيث التكلفة: + + + +```python +from crewai import Agent, LLM +from portkey_ai import createHeaders, PORTKEY_GATEWAY_URL + +# Configure LLM with simple caching +portkey_llm = LLM( + model="gpt-4o", + base_url=PORTKEY_GATEWAY_URL, + api_key="dummy", + extra_headers=createHeaders( + api_key="YOUR_PORTKEY_API_KEY", + virtual_key="YOUR_OPENAI_VIRTUAL_KEY", + config={ + "cache": { + "mode": "simple" + } + } + ) +) + +# Create agent with cached LLM +researcher = Agent( + role="Senior Research Scientist", + goal="Discover groundbreaking insights about the assigned topic", + backstory="You are an expert researcher with deep domain knowledge.", + verbose=True, + llm=portkey_llm +) +``` + +يقوم التخزين المؤقت البسيط بمطابقة دقيقة لموجهات الإدخال، مع تخزين الطلبات المتطابقة لتجنب عمليات تنفيذ النموذج الزائدة. + + + +```python +from crewai import Agent, LLM +from portkey_ai import createHeaders, PORTKEY_GATEWAY_URL + +# Configure LLM with semantic caching +portkey_llm = LLM( + model="gpt-4o", + base_url=PORTKEY_GATEWAY_URL, + api_key="dummy", + extra_headers=createHeaders( + api_key="YOUR_PORTKEY_API_KEY", + virtual_key="YOUR_OPENAI_VIRTUAL_KEY", + config={ + "cache": { + "mode": "semantic" + } + } + ) +) + +# Create agent with semantically cached LLM +researcher = Agent( + role="Senior Research Scientist", + goal="Discover groundbreaking insights about the assigned topic", + backstory="You are an expert researcher with deep domain knowledge.", + verbose=True, + llm=portkey_llm +) +``` + +يأخذ التخزين المؤقت الدلالي في الاعتبار التشابه السياقي بين طلبات الإدخال، مع تخزين الاستجابات للمدخلات المتشابهة دلالياً. + + + +### 7. التوافق بين النماذج + +يدعم CrewAI مزودي LLM متعددين، ويوسّع Portkey هذه القدرة من خلال توفير الوصول إلى أكثر من 200 نموذج LLM عبر واجهة موحدة. يمكنك التبديل بسهولة بين نماذج مختلفة دون تغيير منطق الوكيل الأساسي: + +```python +from crewai import Agent, LLM +from portkey_ai import createHeaders, PORTKEY_GATEWAY_URL + +# Set up LLMs with different providers +openai_llm = LLM( + model="gpt-4o", + base_url=PORTKEY_GATEWAY_URL, + api_key="dummy", + extra_headers=createHeaders( + api_key="YOUR_PORTKEY_API_KEY", + virtual_key="YOUR_OPENAI_VIRTUAL_KEY" + ) +) + +anthropic_llm = LLM( + model="claude-3-5-sonnet-latest", + max_tokens=1000, + base_url=PORTKEY_GATEWAY_URL, + api_key="dummy", + extra_headers=createHeaders( + api_key="YOUR_PORTKEY_API_KEY", + virtual_key="YOUR_ANTHROPIC_VIRTUAL_KEY" + ) +) + +# Choose which LLM to use for each agent based on your needs +researcher = Agent( + role="Senior Research Scientist", + goal="Discover groundbreaking insights about the assigned topic", + backstory="You are an expert researcher with deep domain knowledge.", + verbose=True, + llm=openai_llm # Use anthropic_llm for Anthropic +) +``` + +يوفر Portkey الوصول إلى نماذج LLM من مزودين بما في ذلك: + +- OpenAI (GPT-4o، GPT-4 Turbo، إلخ) +- Anthropic (Claude 3.5 Sonnet، Claude 3 Opus، إلخ) +- Mistral AI (Mistral Large، Mistral Medium، إلخ) +- Google Vertex AI (Gemini 1.5 Pro، إلخ) +- Cohere (Command، Command-R، إلخ) +- AWS Bedrock (Claude، Titan، إلخ) +- النماذج المحلية/الخاصة + + + اطلع على القائمة الكاملة لمزودي LLM المدعومين من Portkey + + +## إعداد حوكمة المؤسسة لـ CrewAI + +**لماذا حوكمة المؤسسة؟** +إذا كنت تستخدم CrewAI داخل مؤسستك، فأنت بحاجة إلى مراعاة عدة جوانب حوكمة: +- **إدارة التكاليف**: التحكم في إنفاق الذكاء الاصطناعي وتتبعه عبر الفرق +- **التحكم في الوصول**: إدارة الفرق التي يمكنها استخدام نماذج محددة +- **تحليلات الاستخدام**: فهم كيفية استخدام الذكاء الاصطناعي عبر المؤسسة +- **الأمان والامتثال**: الحفاظ على معايير أمان المؤسسة +- **الموثوقية**: ضمان خدمة متسقة لجميع المستخدمين + +يضيف Portkey طبقة حوكمة شاملة لتلبية احتياجات المؤسسة هذه. لننفّذ هذه الضوابط خطوة بخطوة. + + + +المفاتيح الافتراضية هي طريقة Portkey الآمنة لإدارة مفاتيح API لمزودي LLM. توفر ضوابط أساسية مثل: +- حدود الميزانية لاستخدام API +- إمكانيات تحديد المعدل +- تخزين آمن لمفاتيح API + +لإنشاء مفتاح افتراضي: +انتقل إلى [المفاتيح الافتراضية](https://app.portkey.ai/virtual-keys) في تطبيق Portkey. احفظ وانسخ معرّف المفتاح الافتراضي + + + + + + +احفظ معرّف المفتاح الافتراضي - ستحتاجه في الخطوة التالية. + + + + +تحدد التكوينات في Portkey كيفية توجيه طلباتك، مع ميزات مثل التوجيه المتقدم والاحتياط وإعادة المحاولة. + +لإنشاء تكوينك: +1. انتقل إلى [التكوينات](https://app.portkey.ai/configs) في لوحة تحكم Portkey +2. أنشئ تكويناً جديداً بـ: + ```json + { + "virtual_key": "YOUR_VIRTUAL_KEY_FROM_STEP1", + "override_params": { + "model": "gpt-4o" // Your preferred model name + } + } + ``` +3. احفظ ولاحظ اسم التكوين للخطوة التالية + + + + + + + + +الآن أنشئ مفتاح API لـ Portkey وأرفق التكوين الذي أنشأته في الخطوة 2: + +1. انتقل إلى [مفاتيح API](https://app.portkey.ai/api-keys) في Portkey وأنشئ مفتاح API جديد +2. حدد تكوينك من `الخطوة 2` +3. أنشئ واحفظ مفتاح API الخاص بك + + + + + + + + +بعد إعداد مفتاح API لـ Portkey مع التكوين المرفق، اربطه بوكلاء CrewAI: + +```python +from crewai import Agent, LLM +from portkey_ai import PORTKEY_GATEWAY_URL + +# Configure LLM with your API key +portkey_llm = LLM( + model="gpt-4o", + base_url=PORTKEY_GATEWAY_URL, + api_key="YOUR_PORTKEY_API_KEY" +) + +# Create agent with Portkey-enabled LLM +researcher = Agent( + role="Senior Research Scientist", + goal="Discover groundbreaking insights about the assigned topic", + backstory="You are an expert researcher with deep domain knowledge.", + verbose=True, + llm=portkey_llm +) +``` + + + + + +### الخطوة 1: تطبيق ضوابط الميزانية وحدود المعدل + +تمكّن المفاتيح الافتراضية التحكم الدقيق في الوصول إلى LLM على مستوى الفريق/القسم. يساعدك هذا على: +- إعداد [حدود الميزانية](https://portkey.ai/docs/product/ai-gateway/virtual-keys/budget-limits) +- منع الارتفاعات غير المتوقعة في الاستخدام باستخدام حدود المعدل +- تتبع إنفاق الأقسام + +#### إعداد ضوابط خاصة بالقسم: +1. انتقل إلى [المفاتيح الافتراضية](https://app.portkey.ai/virtual-keys) في لوحة تحكم Portkey +2. أنشئ مفتاحاً افتراضياً جديداً لكل قسم مع حدود ميزانية ومعدل +3. هيئ الحدود الخاصة بكل قسم + + + + + + + +### الخطوة 2: تحديد قواعد الوصول للنماذج + +مع توسع استخدام الذكاء الاصطناعي، يصبح التحكم في الفرق التي يمكنها الوصول إلى نماذج محددة أمراً بالغ الأهمية. توفر تكوينات Portkey طبقة التحكم هذه مع ميزات مثل: + +#### ميزات التحكم في الوصول: +- **قيود النماذج**: تقييد الوصول إلى نماذج محددة +- **حماية البيانات**: تطبيق حواجز حماية للبيانات الحساسة +- **ضوابط الموثوقية**: إضافة احتياط ومنطق إعادة المحاولة + +#### مثال على التكوين: +إليك تكويناً أساسياً لتوجيه الطلبات إلى OpenAI، تحديداً باستخدام GPT-4o: + +```json +{ + "strategy": { + "mode": "single" + }, + "targets": [ + { + "virtual_key": "YOUR_OPENAI_VIRTUAL_KEY", + "override_params": { + "model": "gpt-4o" + } + } + ] +} +``` + + أنشئ تكوينك في [صفحة التكوينات](https://app.portkey.ai/configs) في لوحة تحكم Portkey. + + + يمكن تحديث التكوينات في أي وقت لضبط الضوابط دون التأثير على التطبيقات قيد التشغيل. + + + + + ### الخطوة 3: تطبيق ضوابط الوصول + + أنشئ مفاتيح API خاصة بالمستخدم تقوم تلقائياً بـ: + - تتبع الاستخدام لكل مستخدم/فريق بمساعدة المفاتيح الافتراضية + - تطبيق التكوينات المناسبة لتوجيه الطلبات + - جمع البيانات الوصفية ذات الصلة لتصفية السجلات + - فرض أذونات الوصول + + أنشئ مفاتيح API من خلال [تطبيق Portkey](https://app.portkey.ai/) + + مثال باستخدام Python SDK: + ```python + from portkey_ai import Portkey + + portkey = Portkey(api_key="YOUR_ADMIN_API_KEY") + + api_key = portkey.api_keys.create( + name="engineering-team", + type="organisation", + workspace_id="YOUR_WORKSPACE_ID", + defaults={ + "config_id": "your-config-id", + "metadata": { + "environment": "production", + "department": "engineering" + } + }, + scopes=["logs.view", "configs.read"] + ) + ``` + + للحصول على تعليمات تفصيلية لإدارة المفاتيح، راجع [وثائق Portkey](https://portkey.ai/docs). + + + + ### الخطوة 4: النشر والمراقبة + بعد توزيع مفاتيح API على أعضاء فريقك، يصبح إعداد CrewAI الجاهز للمؤسسة جاهزاً للعمل. يمكن لكل عضو في الفريق الآن استخدام مفاتيح API المخصصة له مع مستويات وصول وضوابط ميزانية مناسبة. + + راقب الاستخدام في لوحة تحكم Portkey: + - تتبع التكاليف حسب القسم + - أنماط استخدام النماذج + - حجم الطلبات + - معدلات الأخطاء + + + + + +### ميزات المؤسسة متاحة الآن +**تكامل CrewAI الخاص بك يتضمن الآن:** +- ضوابط ميزانية للأقسام +- حوكمة الوصول للنماذج +- تتبع الاستخدام والإسناد +- حواجز أمان +- ميزات الموثوقية + + +## الأسئلة الشائعة + + + + يضيف Portkey جاهزية الإنتاج لـ CrewAI من خلال مراقبة شاملة (تتبعات وسجلات ومقاييس) وميزات موثوقية (احتياط وإعادة محاولة وتخزين مؤقت) والوصول إلى أكثر من 200 نموذج LLM عبر واجهة موحدة. هذا يسهّل تصحيح الأخطاء وتحسين وتوسيع تطبيقات الوكلاء. + + + + نعم! يتكامل Portkey بسلاسة مع تطبيقات CrewAI الحالية. ما عليك سوى تحديث كود تكوين LLM بالنسخة المُمكّنة من Portkey. يبقى باقي كود الوكيل والطاقم دون تغيير. + + + + يدعم Portkey جميع ميزات CrewAI، بما في ذلك الوكلاء والأدوات وسير العمل مع تدخل بشري وجميع أنواع عمليات المهام (تسلسلي وهرمي وغيرها). يضيف المراقبة والموثوقية دون تقييد أي من وظائف الإطار. + + + + نعم، يتيح لك Portkey استخدام `trace_id` متسق عبر وكلاء متعددين في طاقم لتتبع سير العمل بالكامل. هذا مفيد بشكل خاص للطواقم المعقدة حيث تريد فهم مسار التنفيذ الكامل عبر وكلاء متعددين. + + + + يتيح لك Portkey إضافة بيانات وصفية مخصصة لتكوين LLM، والتي يمكنك استخدامها للتصفية. أضف حقولاً مثل `crew_name` أو `crew_type` أو `session_id` للعثور على عمليات تنفيذ طاقم محددة وتحليلها بسهولة. + + + + نعم! يستخدم Portkey مفاتيح API الخاصة بك لمزودي LLM المختلفين. يخزنها بشكل آمن كمفاتيح افتراضية، مما يتيح لك إدارة وتدوير المفاتيح بسهولة دون تغيير كودك. + + + + +## الموارد + + + +

وثائق CrewAI الرسمية

+ + +

احصل على إرشادات مخصصة لتنفيذ هذا التكامل

+ + diff --git a/docs/ar/observability/tracing.mdx b/docs/ar/observability/tracing.mdx new file mode 100644 index 000000000..234a62fcd --- /dev/null +++ b/docs/ar/observability/tracing.mdx @@ -0,0 +1,214 @@ +--- +title: تتبع CrewAI +description: التتبع المدمج لطواقم وتدفقات CrewAI مع منصة CrewAI AMP +icon: magnifying-glass-chart +mode: "wide" +--- + +# التتبع المدمج في CrewAI + +يوفر CrewAI إمكانيات تتبع مدمجة تتيح لك مراقبة وتصحيح أخطاء الطواقم والتدفقات في الوقت الفعلي. يوضح هذا الدليل كيفية تفعيل التتبع لكل من **الطواقم** و**التدفقات** باستخدام منصة المراقبة المتكاملة في CrewAI. + +> **ما هو تتبع CrewAI؟** يوفر التتبع المدمج في CrewAI مراقبة شاملة لوكلاء الذكاء الاصطناعي، بما في ذلك قرارات الوكلاء وجداول تنفيذ المهام واستخدام الأدوات واستدعاءات LLM - كل ذلك متاح عبر [منصة CrewAI AMP](https://app.crewai.com). + +![واجهة تتبع CrewAI](/images/crewai-tracing.png) + +## المتطلبات الأساسية + +قبل أن تتمكن من استخدام تتبع CrewAI، تحتاج إلى: + +1. **حساب CrewAI AMP**: سجّل للحصول على حساب مجاني على [app.crewai.com](https://app.crewai.com) +2. **مصادقة CLI**: استخدم CLI الخاص بـ CrewAI لمصادقة بيئتك المحلية + +```bash +crewai login +``` + +## تعليمات الإعداد + +### الخطوة 1: إنشاء حساب CrewAI AMP + +قم بزيارة [app.crewai.com](https://app.crewai.com) وأنشئ حسابك المجاني. سيمنحك هذا الوصول إلى منصة CrewAI AMP حيث يمكنك عرض التتبعات والمقاييس وإدارة طواقمك. + +### الخطوة 2: تثبيت CLI الخاص بـ CrewAI والمصادقة + +إذا لم تكن قد فعلت ذلك بالفعل، ثبّت CrewAI مع أدوات CLI: + +```bash +uv add 'crewai[tools]' +``` + +ثم صادق على CLI مع حساب CrewAI AMP الخاص بك: + +```bash +crewai login +``` + +سيقوم هذا الأمر بـ: + +1. فتح متصفحك إلى صفحة المصادقة +2. طلب إدخال رمز الجهاز +3. مصادقة بيئتك المحلية مع حساب CrewAI AMP +4. تفعيل إمكانيات التتبع لتطويرك المحلي + +### الخطوة 3: تفعيل التتبع في طاقمك + +يمكنك تفعيل التتبع لطاقمك عبر تعيين معامل `tracing` إلى `True`: + +```python +from crewai import Agent, Crew, Process, Task +from crewai_tools import SerperDevTool + +# Define your agents +researcher = Agent( + role="Senior Research Analyst", + goal="Uncover cutting-edge developments in AI and data science", + backstory="""You work at a leading tech think tank. + Your expertise lies in identifying emerging trends. + You have a knack for dissecting complex data and presenting actionable insights.""", + verbose=True, + tools=[SerperDevTool()], +) + +writer = Agent( + role="Tech Content Strategist", + goal="Craft compelling content on tech advancements", + backstory="""You are a renowned Content Strategist, known for your insightful and engaging articles. + You transform complex concepts into compelling narratives.""", + verbose=True, +) + +# Create tasks for your agents +research_task = Task( + description="""Conduct a comprehensive analysis of the latest advancements in AI in 2024. + Identify key trends, breakthrough technologies, and potential industry impacts.""", + expected_output="Full analysis report in bullet points", + agent=researcher, +) + +writing_task = Task( + description="""Using the insights provided, develop an engaging blog + post that highlights the most significant AI advancements. + Your post should be informative yet accessible, catering to a tech-savvy audience.""", + expected_output="Full blog post of at least 4 paragraphs", + agent=writer, +) + +# Enable tracing in your crew +crew = Crew( + agents=[researcher, writer], + tasks=[research_task, writing_task], + process=Process.sequential, + tracing=True, # Enable built-in tracing + verbose=True +) + +# Execute your crew +result = crew.kickoff() +``` + +### الخطوة 4: تفعيل التتبع في التدفق + +بالمثل، يمكنك تفعيل التتبع لتدفقات CrewAI: + +```python +from crewai.flow.flow import Flow, listen, start +from pydantic import BaseModel + +class ExampleState(BaseModel): + counter: int = 0 + message: str = "" + +class ExampleFlow(Flow[ExampleState]): + def __init__(self): + super().__init__(tracing=True) # Enable tracing for the flow + + @start() + def first_method(self): + print("Starting the flow") + self.state.counter = 1 + self.state.message = "Flow started" + return "continue" + + @listen("continue") + def second_method(self): + print("Continuing the flow") + self.state.counter += 1 + self.state.message = "Flow continued" + return "finish" + + @listen("finish") + def final_method(self): + print("Finishing the flow") + self.state.counter += 1 + self.state.message = "Flow completed" + +# Create and run the flow with tracing enabled +flow = ExampleFlow(tracing=True) +result = flow.kickoff() +``` + +### الخطوة 5: عرض التتبعات في لوحة تحكم CrewAI AMP + +بعد تشغيل الطاقم أو التدفق، يمكنك عرض التتبعات التي أنشأها تطبيق CrewAI في لوحة تحكم CrewAI AMP. يجب أن ترى خطوات تفصيلية لتفاعلات الوكلاء واستخدامات الأدوات واستدعاءات LLM. +ما عليك سوى النقر على الرابط أدناه لعرض التتبعات أو التوجه إلى علامة تبويب التتبعات في لوحة التحكم [هنا](https://app.crewai.com/crewai_plus/trace_batches) +![واجهة تتبع CrewAI](/images/view-traces.png) + +### البديل: إعداد متغير البيئة + +يمكنك أيضاً تفعيل التتبع عالمياً عبر تعيين متغير بيئة: + +```bash +export CREWAI_TRACING_ENABLED=true +``` + +أو إضافته إلى ملف `.env`: + +```env +CREWAI_TRACING_ENABLED=true +``` + +عند تعيين متغير البيئة هذا، ستُفعّل جميع الطواقم والتدفقات التتبع تلقائياً، حتى بدون تعيين `tracing=True` صراحةً. + +## عرض التتبعات + +### الوصول إلى لوحة تحكم CrewAI AMP + +1. قم بزيارة [app.crewai.com](https://app.crewai.com) وسجّل الدخول إلى حسابك +2. انتقل إلى لوحة تحكم مشروعك +3. انقر على علامة تبويب **التتبعات** لعرض تفاصيل التنفيذ + +### ما ستراه في التتبعات + +يوفر تتبع CrewAI رؤية شاملة لـ: + +- **قرارات الوكلاء**: شاهد كيف يفكر الوكلاء في المهام ويتخذون القرارات +- **جدول تنفيذ المهام**: تمثيل مرئي لتسلسلات المهام والتبعيات +- **استخدام الأدوات**: مراقبة الأدوات المستدعاة ونتائجها +- **استدعاءات LLM**: تتبع جميع تفاعلات نماذج اللغة، بما في ذلك الموجهات والاستجابات +- **مقاييس الأداء**: أوقات التنفيذ واستخدام الرموز المميزة والتكاليف +- **تتبع الأخطاء**: معلومات تفصيلية عن الأخطاء وتتبعات المكدس + +### ميزات التتبع + +- **جدول التنفيذ**: انقر عبر مراحل التنفيذ المختلفة +- **سجلات تفصيلية**: الوصول إلى سجلات شاملة لتصحيح الأخطاء +- **تحليلات الأداء**: حلّل أنماط التنفيذ وحسّن الأداء +- **إمكانيات التصدير**: حمّل التتبعات لمزيد من التحليل + +### مشكلات المصادقة + +إذا واجهت مشاكل في المصادقة: + +1. تأكد من تسجيل الدخول: `crewai login` +2. تحقق من اتصال الإنترنت +3. تحقق من حسابك على [app.crewai.com](https://app.crewai.com) + +### التتبعات لا تظهر + +إذا لم تظهر التتبعات في لوحة التحكم: + +1. تأكد من تعيين `tracing=True` في الطاقم/التدفق +2. تحقق من `CREWAI_TRACING_ENABLED=true` إذا كنت تستخدم متغيرات البيئة +3. تأكد من المصادقة عبر `crewai login` +4. تحقق من أن الطاقم/التدفق قيد التنفيذ فعلاً diff --git a/docs/ar/observability/truefoundry.mdx b/docs/ar/observability/truefoundry.mdx new file mode 100644 index 000000000..9260f43fc --- /dev/null +++ b/docs/ar/observability/truefoundry.mdx @@ -0,0 +1,146 @@ +--- +title: تكامل TrueFoundry +icon: chart-line +mode: "wide" +--- + +توفر TrueFoundry [بوابة ذكاء اصطناعي](https://www.truefoundry.com/ai-gateway) جاهزة للمؤسسات يمكنها التكامل مع أطر العمل الوكيلية مثل CrewAI وتوفير الحوكمة والمراقبة لتطبيقات الذكاء الاصطناعي. تعمل بوابة TrueFoundry AI كواجهة موحدة للوصول إلى LLM، وتوفر: + +- **وصول موحد لـ API**: الاتصال بأكثر من 250 نموذج LLM (OpenAI وClaude وGemini وGroq وMistral) عبر API واحد +- **زمن استجابة منخفض**: زمن استجابة داخلي أقل من 3 مللي ثانية مع توجيه ذكي وموازنة أحمال +- **أمان المؤسسة**: امتثال SOC 2 وHIPAA وGDPR مع RBAC وتسجيل المراجعة +- **إدارة الحصص والتكاليف**: حصص قائمة على الرموز المميزة وتحديد المعدل وتتبع استخدام شامل +- **المراقبة**: تسجيل كامل للطلبات/الاستجابات ومقاييس وتتبعات مع احتفاظ قابل للتخصيص + +## كيف يتكامل TrueFoundry مع CrewAI + + +### التثبيت والإعداد + + + +```bash +pip install crewai +``` + + + +1. سجّل في [حساب TrueFoundry](https://www.truefoundry.com/register) +2. اتبع الخطوات هنا في [البدء السريع](https://docs.truefoundry.com/gateway/quick-start) + + + +![إعداد كود TrueFoundry](/images/new-code-snippet.png) + +```python +from crewai import LLM + +# Create an LLM instance with TrueFoundry AI Gateway +truefoundry_llm = LLM( + model="openai-main/gpt-4o", # Similarly, you can call any model from any provider + base_url="your_truefoundry_gateway_base_url", + api_key="your_truefoundry_api_key" +) + +# Use in your CrewAI agents +from crewai import Agent + +@agent +def researcher(self) -> Agent: + return Agent( + config=self.agents_config['researcher'], + llm=truefoundry_llm, + verbose=True + ) +``` + + + +### مثال كامل على CrewAI + +```python +from crewai import Agent, Task, Crew, LLM + +# Configure LLM with TrueFoundry +llm = LLM( + model="openai-main/gpt-4o", + base_url="your_truefoundry_gateway_base_url", + api_key="your_truefoundry_api_key" +) + +# Create agents +researcher = Agent( + role='Research Analyst', + goal='Conduct detailed market research', + backstory='Expert market analyst with attention to detail', + llm=llm, + verbose=True +) + +writer = Agent( + role='Content Writer', + goal='Create comprehensive reports', + backstory='Experienced technical writer', + llm=llm, + verbose=True +) + +# Create tasks +research_task = Task( + description='Research AI market trends for 2024', + agent=researcher, + expected_output='Comprehensive research summary' +) + +writing_task = Task( + description='Create a market research report', + agent=writer, + expected_output='Well-structured report with insights', + context=[research_task] +) + +# Create and execute crew +crew = Crew( + agents=[researcher, writer], + tasks=[research_task, writing_task], + verbose=True +) + +result = crew.kickoff() +``` + +### المراقبة والحوكمة + +راقب وكلاء CrewAI من خلال علامة تبويب المقاييس في TrueFoundry: +![مقاييس TrueFoundry](/images/gateway-metrics.png) + +مع بوابة الذكاء الاصطناعي من TrueFoundry، يمكنك مراقبة وتحليل: + +- **مقاييس الأداء**: تتبع مقاييس زمن الاستجابة الرئيسية مثل زمن استجابة الطلب ووقت أول رمز (TTFS) وزمن الاستجابة بين الرموز (ITL) بنسب مئوية P99 وP90 وP50 +- **التكلفة واستخدام الرموز المميزة**: احصل على رؤية لتكاليف تطبيقك مع تفاصيل دقيقة لرموز الإدخال/الإخراج والنفقات المرتبطة لكل نموذج +- **أنماط الاستخدام**: افهم كيف يُستخدم تطبيقك مع تحليلات تفصيلية لنشاط المستخدم وتوزيع النماذج والاستخدام حسب الفريق +- **تحديد المعدل وموازنة الأحمال**: يمكنك إعداد تحديد المعدل وموازنة الأحمال والاحتياط لنماذجك + +## التتبع + +لفهم أعمق حول التتبع، يرجى مراجعة [البدء بالتتبع](https://docs.truefoundry.com/docs/tracing/tracing-getting-started). للتتبع، يمكنك إضافة Traceloop SDK: + +```bash +pip install traceloop-sdk +``` + +```python +from traceloop.sdk import Traceloop + +# Initialize enhanced tracing +Traceloop.init( + api_endpoint="https://your-truefoundry-endpoint/api/tracing", + headers={ + "Authorization": f"Bearer {your_truefoundry_pat_token}", + "TFY-Tracing-Project": "your_project_name", + }, +) +``` + +يوفر هذا ارتباط تتبع إضافي عبر سير عمل CrewAI بالكامل. +![تتبع CrewAI مع TrueFoundry](/images/tracing_crewai.png) diff --git a/docs/ar/observability/weave.mdx b/docs/ar/observability/weave.mdx new file mode 100644 index 000000000..c2ded9a86 --- /dev/null +++ b/docs/ar/observability/weave.mdx @@ -0,0 +1,125 @@ +--- +title: تكامل Weave +description: تعرّف على كيفية استخدام Weights & Biases (W&B) Weave لتتبع وتجربة وتقييم وتحسين تطبيقات CrewAI. +icon: radar +mode: "wide" +--- + +# نظرة عامة على Weave + +[Weights & Biases (W&B) Weave](https://weave-docs.wandb.ai/) هو إطار عمل لتتبع وتجربة وتقييم ونشر وتحسين التطبيقات المبنية على نماذج اللغة الكبيرة. + +![نظرة عامة على استخدام تتبع W&B Weave مع CrewAI](/images/weave-tracing.gif) + +يوفر Weave دعماً شاملاً لكل مرحلة من مراحل تطوير تطبيق CrewAI: + +- **التتبع والمراقبة**: تتبع تلقائي لاستدعاءات LLM ومنطق التطبيق لتصحيح الأخطاء وتحليل أنظمة الإنتاج +- **التكرار المنهجي**: تحسين والتكرار على الموجهات ومجموعات البيانات والنماذج +- **التقييم**: استخدام مقيّمين مخصصين أو مُعدّين مسبقاً لتقييم أداء الوكلاء وتحسينه بشكل منهجي +- **حواجز الحماية**: حماية وكلائك بحماية مسبقة ولاحقة للإشراف على المحتوى وسلامة الموجهات + +يلتقط Weave التتبعات تلقائياً لتطبيقات CrewAI، مما يمكّنك من مراقبة وتحليل أداء وكلائك وتفاعلاتهم وتدفق التنفيذ. يساعدك هذا في بناء مجموعات بيانات تقييم أفضل وتحسين سير عمل وكلائك. + +## تعليمات الإعداد + + + + ```shell + pip install crewai weave + ``` + + + سجّل في [حساب Weights & Biases](https://wandb.ai) إذا لم تكن قد فعلت ذلك بالفعل. ستحتاج إليه لعرض التتبعات والمقاييس. + + + أضف الكود التالي إلى تطبيقك: + + ```python + import weave + + # Initialize Weave with your project name + weave.init(project_name="crewai_demo") + ``` + + بعد التهيئة، سيوفر Weave عنوان URL حيث يمكنك عرض التتبعات والمقاييس. + + + ```python + from crewai import Agent, Task, Crew, LLM, Process + + # Create an LLM with a temperature of 0 to ensure deterministic outputs + llm = LLM(model="gpt-4o", temperature=0) + + # Create agents + researcher = Agent( + role='Research Analyst', + goal='Find and analyze the best investment opportunities', + backstory='Expert in financial analysis and market research', + llm=llm, + verbose=True, + allow_delegation=False, + ) + + writer = Agent( + role='Report Writer', + goal='Write clear and concise investment reports', + backstory='Experienced in creating detailed financial reports', + llm=llm, + verbose=True, + allow_delegation=False, + ) + + # Create tasks + research_task = Task( + description='Deep research on the {topic}', + expected_output='Comprehensive market data including key players, market size, and growth trends.', + agent=researcher + ) + + writing_task = Task( + description='Write a detailed report based on the research', + expected_output='The report should be easy to read and understand. Use bullet points where applicable.', + agent=writer + ) + + # Create a crew + crew = Crew( + agents=[researcher, writer], + tasks=[research_task, writing_task], + verbose=True, + process=Process.sequential, + ) + + # Run the crew + result = crew.kickoff(inputs={"topic": "AI in material science"}) + print(result) + ``` + + + بعد تشغيل تطبيق CrewAI، قم بزيارة عنوان URL الذي وفره Weave أثناء التهيئة لعرض: + - استدعاءات LLM وبياناتها الوصفية + - تفاعلات الوكلاء وتدفق تنفيذ المهام + - مقاييس الأداء مثل زمن الاستجابة واستخدام الرموز المميزة + - أي أخطاء أو مشكلات حدثت أثناء التنفيذ + + + Weave tracing example with CrewAI + + + + +## الميزات + +- يلتقط Weave تلقائياً جميع عمليات CrewAI: تفاعلات الوكلاء وتنفيذ المهام؛ استدعاءات LLM مع البيانات الوصفية واستخدام الرموز المميزة؛ استخدام الأدوات ونتائجها. +- يدعم التكامل جميع طرق تنفيذ CrewAI: `kickoff()` و`kickoff_for_each()` و`kickoff_async()` و`kickoff_for_each_async()`. +- تتبع تلقائي لجميع [أدوات crewAI](https://github.com/crewAIInc/crewAI-tools). +- دعم ميزة التدفق مع تصحيح المزخرفات (`@start` و`@listen` و`@router` و`@or_` و`@and_`). +- تتبع حواجز الحماية المخصصة المُمررة لمهام CrewAI `Task` باستخدام `@weave.op()`. + +لمعلومات تفصيلية حول ما هو مدعوم، قم بزيارة [وثائق Weave CrewAI](https://weave-docs.wandb.ai/guides/integrations/crewai/#getting-started-with-flow). + +## الموارد + +- [وثائق Weave](https://weave-docs.wandb.ai) +- [مثال على لوحة معلومات Weave x CrewAI](https://wandb.ai/ayut/crewai_demo/weave/traces?cols=%7B%22wb_run_id%22%3Afalse%2C%22attributes.weave.client_version%22%3Afalse%2C%22attributes.weave.os_name%22%3Afalse%2C%22attributes.weave.os_release%22%3Afalse%2C%22attributes.weave.os_version%22%3Afalse%2C%22attributes.weave.source%22%3Afalse%2C%22attributes.weave.sys_version%22%3Afalse%7D&peekPath=%2Fayut%2Fcrewai_demo%2Fcalls%2F0195c838-38cb-71a2-8a15-651ecddf9d89) +- [X](https://x.com/weave_wb) diff --git a/docs/ar/quickstart.mdx b/docs/ar/quickstart.mdx new file mode 100644 index 000000000..ee1419c39 --- /dev/null +++ b/docs/ar/quickstart.mdx @@ -0,0 +1,278 @@ +--- +title: البدء السريع +description: ابنِ أول Flow في CrewAI خلال دقائق — التنسيق والحالة وفريقًا بوكيل واحد ينتج تقريرًا فعليًا. +icon: rocket +mode: "wide" +--- + +### شاهد: بناء Agents و Flows في CrewAI باستخدام Coding Agent Skills + +قم بتثبيت مهارات وكيل البرمجة الخاصة بنا (Claude Code، Codex، ...) لتشغيل وكلاء البرمجة بسرعة مع CrewAI. + +يمكنك تثبيتها باستخدام `npx skills add crewaiinc/skills` + + + +في هذا الدليل ستُنشئ **Flow** يحدد موضوع بحث، ويشغّل **طاقمًا بوكيل واحد** (باحث يستخدم البحث على الويب)، وينتهي بتقرير **Markdown** على القرص. يُعد Flow الطريقة الموصى بها لتنظيم التطبيقات الإنتاجية: يمتلك **الحالة** و**ترتيب التنفيذ**، بينما **الوكلاء** ينفّذون العمل داخل خطوة الطاقم. + +إذا لم تُكمل تثبيت CrewAI بعد، اتبع [دليل التثبيت](/ar/installation) أولًا. + +## المتطلبات الأساسية + +- بيئة Python وواجهة سطر أوامر CrewAI (راجع [التثبيت](/ar/installation)) +- نموذج لغوي مهيأ بالمفاتيح الصحيحة — راجع [LLMs](/ar/concepts/llms#setting-up-your-llm) +- مفتاح API من [Serper.dev](https://serper.dev/) (`SERPER_API_KEY`) للبحث على الويب في هذا الدرس + +## ابنِ أول Flow لك + + + + من الطرفية، أنشئ مشروع Flow (اسم المجلد يستخدم شرطة سفلية، مثل `latest_ai_flow`): + + + ```shell Terminal + crewai create flow latest-ai-flow + cd latest_ai_flow + ``` + + + يُنشئ ذلك تطبيق Flow ضمن `src/latest_ai_flow/`، بما في ذلك طاقمًا أوليًا في `crews/content_crew/` ستستبدله بطاقم بحث **بوكيل واحد** في الخطوات التالية. + + + + استبدل محتوى `src/latest_ai_flow/crews/content_crew/config/agents.yaml` بباحث واحد. تُملأ المتغيرات مثل `{topic}` من `crew.kickoff(inputs=...)`. + + ```yaml agents.yaml + # src/latest_ai_flow/crews/content_crew/config/agents.yaml + researcher: + role: > + باحث بيانات أول في {topic} + goal: > + اكتشاف أحدث التطورات في {topic} + backstory: > + أنت باحث مخضرم تكشف أحدث المستجدات في {topic}. + تجد المعلومات الأكثر صلة وتعرضها بوضوح. + ``` + + + + + ```yaml tasks.yaml + # src/latest_ai_flow/crews/content_crew/config/tasks.yaml + research_task: + description: > + أجرِ بحثًا معمقًا عن {topic}. استخدم البحث على الويب للعثور على معلومات + حديثة وموثوقة. السنة الحالية 2026. + expected_output: > + تقرير بصيغة Markdown بأقسام واضحة: الاتجاهات الرئيسية، أدوات أو شركات بارزة، + والآثار. بين 800 و1200 كلمة تقريبًا. دون إحاطة المستند بأكمله بكتل كود. + agent: researcher + output_file: output/report.md + ``` + + + + + اجعل الطاقم المُولَّد يشير إلى YAML وأرفق `SerperDevTool` بالباحث. + + ```python content_crew.py + # src/latest_ai_flow/crews/content_crew/content_crew.py + from typing import List + + from crewai import Agent, Crew, Process, Task + from crewai.agents.agent_builder.base_agent import BaseAgent + from crewai.project import CrewBase, agent, crew, task + from crewai_tools import SerperDevTool + + + @CrewBase + class ResearchCrew: + """طاقم بحث بوكيل واحد داخل Flow.""" + + agents: List[BaseAgent] + tasks: List[Task] + + agents_config = "config/agents.yaml" + tasks_config = "config/tasks.yaml" + + @agent + def researcher(self) -> Agent: + return Agent( + config=self.agents_config["researcher"], # type: ignore[index] + verbose=True, + tools=[SerperDevTool()], + ) + + @task + def research_task(self) -> Task: + return Task( + config=self.tasks_config["research_task"], # type: ignore[index] + ) + + @crew + def crew(self) -> Crew: + return Crew( + agents=self.agents, + tasks=self.tasks, + process=Process.sequential, + verbose=True, + ) + ``` + + + + + اربط الطاقم بـ Flow: خطوة `@start()` تضبط الموضوع في **الحالة**، وخطوة `@listen` تشغّل الطاقم. يظل `output_file` للمهمة يكتب `output/report.md`. + + ```python main.py + # src/latest_ai_flow/main.py + from pydantic import BaseModel + + from crewai.flow import Flow, listen, start + + from latest_ai_flow.crews.content_crew.content_crew import ResearchCrew + + + class ResearchFlowState(BaseModel): + topic: str = "" + report: str = "" + + + class LatestAiFlow(Flow[ResearchFlowState]): + @start() + def prepare_topic(self, crewai_trigger_payload: dict | None = None): + if crewai_trigger_payload: + self.state.topic = crewai_trigger_payload.get("topic", "AI Agents") + else: + self.state.topic = "AI Agents" + print(f"الموضوع: {self.state.topic}") + + @listen(prepare_topic) + def run_research(self): + result = ResearchCrew().crew().kickoff(inputs={"topic": self.state.topic}) + self.state.report = result.raw + print("اكتمل طاقم البحث.") + + @listen(run_research) + def summarize(self): + print("مسار التقرير: output/report.md") + + + def kickoff(): + LatestAiFlow().kickoff() + + + def plot(): + LatestAiFlow().plot() + + + if __name__ == "__main__": + kickoff() + ``` + + + إذا كان اسم الحزمة ليس `latest_ai_flow`، عدّل استيراد `ResearchCrew` ليطابق مسار الوحدة في مشروعك. + + + + + في جذر المشروع، ضبط `.env`: + + - `SERPER_API_KEY` — من [Serper.dev](https://serper.dev/) + - مفاتيح مزوّد النموذج حسب الحاجة — راجع [إعداد LLM](/ar/concepts/llms#setting-up-your-llm) + + + + + ```shell Terminal + crewai install + crewai run + ``` + + + يُنفّذ `crewai run` نقطة دخول Flow المعرّفة في المشروع (نفس أمر الطواقم؛ نوع المشروع `"flow"` في `pyproject.toml`). + + + + يجب أن ترى سجلات من Flow والطاقم. افتح **`output/report.md`** للتقرير المُولَّد (مقتطف): + + + ```markdown output/report.md + # وكلاء الذكاء الاصطناعي في 2026: المشهد والاتجاهات + + ## ملخص تنفيذي + … + + ## أبرز الاتجاهات + - **استخدام الأدوات والتنسيق** — … + - **التبني المؤسسي** — … + + ## الآثار + … + ``` + + + سيكون الملف الفعلي أطول ويعكس نتائج بحث مباشرة. + + + +## كيف يترابط هذا + +1. **Flow** — يشغّل `LatestAiFlow` أولًا `prepare_topic` ثم `run_research` ثم `summarize`. الحالة (`topic`، `report`) على Flow. +2. **الطاقم** — يشغّل `ResearchCrew` مهمة واحدة بوكيل واحد: الباحث يستخدم **Serper** للبحث على الويب ثم يكتب التقرير. +3. **المُخرَج** — يكتب `output_file` للمهمة التقرير في `output/report.md`. + +للتعمق في أنماط Flow (التوجيه، الاستمرارية، الإنسان في الحلقة)، راجع [ابنِ أول Flow](/ar/guides/flows/first-flow) و[Flows](/ar/concepts/flows). للطواقم دون Flow، راجع [Crews](/ar/concepts/crews). لوكيل `Agent` واحد و`kickoff()` بلا مهام، راجع [Agents](/ar/concepts/agents#direct-agent-interaction-with-kickoff). + + +أصبح لديك Flow كامل مع طاقم وكيل وتقرير محفوظ — قاعدة قوية لإضافة خطوات أو طواقم أو أدوات. + + +### اتساق التسمية + +يجب أن تطابق مفاتيح YAML (`researcher`، `research_task`) أسماء الدوال في صف `@CrewBase`. راجع [Crews](/ar/concepts/crews) لنمط الديكورات الكامل. + +## النشر + +ادفع Flow إلى **[CrewAI AMP](https://app.crewai.com)** بعد أن يعمل محليًا ويكون المشروع في مستودع **GitHub**. من جذر المشروع: + + +```bash المصادقة +crewai login +``` + +```bash إنشاء نشر +crewai deploy create +``` + +```bash الحالة والسجلات +crewai deploy status +crewai deploy logs +``` + +```bash إرسال التحديثات بعد تغيير الكود +crewai deploy push +``` + +```bash عرض النشرات أو حذفها +crewai deploy list +crewai deploy remove +``` + + + + غالبًا ما يستغرق **النشر الأول حوالي دقيقة**. المتطلبات الكاملة ومسار الواجهة الويب في [النشر على AMP](/ar/enterprise/guides/deploy-to-amp). + + + + + النشر على AMP خطوة بخطوة (CLI ولوحة التحكم). + + + ناقش الأفكار وشارك مشاريعك وتواصل مع مطوري CrewAI. + + diff --git a/docs/ar/skills.mdx b/docs/ar/skills.mdx new file mode 100644 index 000000000..4e0bf6e22 --- /dev/null +++ b/docs/ar/skills.mdx @@ -0,0 +1,50 @@ +--- +title: Skills +description: ثبّت crewaiinc/skills من السجل الرسمي على skills.sh—Flows وCrews ووكلاء مرتبطون بالوثائق لـ Claude Code وCursor وCodex وغيرها. +icon: wand-magic-sparkles +mode: "wide" +--- + +# Skills + +**امنح وكيل البرمجة سياق CrewAI في أمر واحد.** + +تُنشر **Skills** الخاصة بـ CrewAI على **[skills.sh/crewaiinc/skills](https://skills.sh/crewaiinc/skills)**—السجل الرسمي لـ `crewaiinc/skills`، بما في ذلك كل مهارة (مثل **design-agent** و**getting-started** و**design-task** و**ask-docs**) وإحصاءات التثبيت والتدقيقات. تعلّم وكلاء البرمجة—مثل Claude Code وCursor وCodex—هيكلة Flows وضبط Crews واستخدام الأدوات واتباع أنماط CrewAI. نفّذ الأمر أدناه (أو الصقه في الوكيل). + +```shell Terminal +npx skills add crewaiinc/skills +``` + +يضيف ذلك حزمة المهارات إلى سير عمل الوكيل لتطبيق اتفاقيات CrewAI دون إعادة شرح الإطار في كل جلسة. المصدر والقضايا على [GitHub](https://github.com/crewAIInc/skills). + +## ما يحصل عليه الوكيل + +- **Flows** — تطبيقات ذات حالة وخطوات وkickoffs للـ crew على نمط CrewAI +- **Crews والوكلاء** — أنماط YAML أولاً، أدوار، مهام، وتفويض +- **الأدوات والتكاملات** — ربط الوكلاء بالبحث وواجهات API وأدوات CrewAI الشائعة +- **هيكل المشروع** — مواءمة مع قوالب CLI واتفاقيات المستودع +- **أنماط محدثة** — تتبع المهارات وثائق CrewAI والممارسات الموصى بها + +## تعرّف أكثر على هذا الموقع + + + + استخدام `AGENTS.md` وسير عمل وكلاء البرمجة مع CrewAI. + + + ابنِ أول Flow وcrew من البداية للنهاية. + + + ثبّت CrewAI CLI وحزمة Python. + + + القائمة الرسمية لـ `crewaiinc/skills`—المهارات والتثبيتات والتدقيقات. + + + مصدر الحزمة والتحديثات والقضايا. + + + +### فيديو: CrewAI مع مهارات وكلاء البرمجة + + + ## Video Tutorial Watch this video tutorial for a step-by-step demonstration of the installation process: @@ -163,6 +171,9 @@ We recommend using the `YAML` template scaffolding for a structured approach to ```shell uv add ``` + + As a supply-chain security measure, CrewAI's internal packages use `exclude-newer = "3 days"` in their `pyproject.toml` files. This means transitive dependencies pulled in by CrewAI won't resolve packages released less than 3 days ago. Your own direct dependencies are not affected by this policy. If you notice a transitive dependency is behind, you can pin the version you want explicitly in your project's dependencies. + - To run your crew, execute the following command in the root of your project: ```bash crewai run @@ -196,9 +207,8 @@ For teams and organizations, CrewAI offers enterprise deployment options that el ## Next Steps - - Follow our quickstart guide to create your first CrewAI agent and get - hands-on experience. + + Follow the quickstart to scaffold a Flow, run a one-agent crew, and produce a report. + ## The CrewAI Architecture CrewAI's architecture is designed to balance autonomy with control. @@ -132,7 +140,7 @@ For any production-ready application, **start with a Flow**. icon="bolt" href="en/quickstart" > - Follow our quickstart guide to create your first CrewAI agent and get hands-on experience. + Scaffold a Flow, run a crew with one agent, and generate a report end to end. + A2UI requires the `a2a-sdk` package. Install with: `uv add 'crewai[a2a]'` or `pip install 'crewai[a2a]'` + + +## How It Works + +1. The **server extension** scans agent output for A2UI JSON objects +2. Valid messages are wrapped as `DataPart` entries with the `application/json+a2ui` MIME type +3. The **client extension** augments the agent's system prompt with A2UI instructions and the component catalog +4. The client tracks surface state (active surfaces and data models) across conversation turns + +## Server Setup + +Add `A2UIServerExtension` to your `A2AServerConfig` to enable A2UI output: + +```python Code +from crewai import Agent +from crewai.a2a import A2AServerConfig +from crewai.a2a.extensions.a2ui import A2UIServerExtension + +agent = Agent( + role="Dashboard Agent", + goal="Present data through interactive UI surfaces", + backstory="Expert at building clear, actionable dashboards", + llm="gpt-4o", + a2a=A2AServerConfig( + url="https://your-server.com", + server_extensions=[A2UIServerExtension()], + ), +) +``` + +### Server Extension Options + + + Component catalog identifiers the server supports. When set, only these catalogs are advertised to clients. + + + + Whether to accept inline catalog definitions from clients in addition to named catalogs. + + +## Client Setup + +Add `A2UIClientExtension` to your `A2AClientConfig` to enable A2UI rendering: + +```python Code +from crewai import Agent +from crewai.a2a import A2AClientConfig +from crewai.a2a.extensions.a2ui import A2UIClientExtension + +agent = Agent( + role="UI Coordinator", + goal="Coordinate tasks and render agent responses as rich UI", + backstory="Expert at presenting agent output in interactive formats", + llm="gpt-4o", + a2a=A2AClientConfig( + endpoint="https://dashboard-agent.example.com/.well-known/agent-card.json", + client_extensions=[A2UIClientExtension()], + ), +) +``` + +### Client Extension Options + + + Preferred component catalog identifier. Defaults to `"standard (v0.8)"` when not set. + + + + Restrict which components the agent may use. When `None`, all 18 standard catalog components are available. + + +## Message Types + +A2UI defines four server-to-client message types. Each message targets a **surface** identified by `surfaceId`. + + + + Initializes a new surface with a root component and optional styles. + + ```json + { + "beginRendering": { + "surfaceId": "dashboard-1", + "root": "main-column", + "catalogId": "standard (v0.8)", + "styles": { + "primaryColor": "#EB6658" + } + } + } + ``` + + + + Sends or updates one or more components on an existing surface. + + ```json + { + "surfaceUpdate": { + "surfaceId": "dashboard-1", + "components": [ + { + "id": "main-column", + "component": { + "Column": { + "children": { "explicitList": ["title", "content"] }, + "alignment": "start" + } + } + }, + { + "id": "title", + "component": { + "Text": { + "text": { "literalString": "Dashboard" }, + "usageHint": "h1" + } + } + } + ] + } + } + ``` + + + + Updates the data model bound to a surface, enabling dynamic content. + + ```json + { + "dataModelUpdate": { + "surfaceId": "dashboard-1", + "path": "/data/model", + "contents": [ + { + "key": "userName", + "valueString": "Alice" + }, + { + "key": "score", + "valueNumber": 42 + } + ] + } + } + ``` + + + + Removes a surface and all its components. + + ```json + { + "deleteSurface": { + "surfaceId": "dashboard-1" + } + } + ``` + + + +## Component Catalog + +A2UI ships with 18 standard components organized into three categories: + +### Content + +| Component | Description | Required Fields | +|-----------|-------------|-----------------| +| **Text** | Renders text with optional heading/body hints | `text` (StringBinding) | +| **Image** | Displays an image with fit and size options | `url` (StringBinding) | +| **Icon** | Renders a named icon from a set of 47 icons | `name` (IconBinding) | +| **Video** | Embeds a video player | `url` (StringBinding) | +| **AudioPlayer** | Embeds an audio player with optional description | `url` (StringBinding) | + +### Layout + +| Component | Description | Required Fields | +|-----------|-------------|-----------------| +| **Row** | Horizontal flex container | `children` (ChildrenDef) | +| **Column** | Vertical flex container | `children` (ChildrenDef) | +| **List** | Scrollable list (vertical or horizontal) | `children` (ChildrenDef) | +| **Card** | Elevated container for a single child | `child` (str) | +| **Tabs** | Tabbed container | `tabItems` (list of TabItem) | +| **Divider** | Visual separator (horizontal or vertical) | — | +| **Modal** | Overlay triggered by an entry point | `entryPointChild`, `contentChild` (str) | + +### Interactive + +| Component | Description | Required Fields | +|-----------|-------------|-----------------| +| **Button** | Clickable button that triggers an action | `child` (str), `action` (Action) | +| **CheckBox** | Boolean toggle with a label | `label` (StringBinding), `value` (BooleanBinding) | +| **TextField** | Text input with type and validation options | `label` (StringBinding) | +| **DateTimeInput** | Date and/or time picker | `value` (StringBinding) | +| **MultipleChoice** | Selection from a list of options | `selections` (ArrayBinding), `options` (list) | +| **Slider** | Numeric range slider | `value` (NumberBinding) | + +## Data Binding + +Components reference values through **bindings** rather than raw literals. This allows surfaces to update dynamically when the data model changes. + +There are two ways to bind a value: + +- **Literal values** — hardcoded directly in the component definition +- **Path references** — point to a key in the surface's data model + +```json +{ + "surfaceUpdate": { + "surfaceId": "profile-1", + "components": [ + { + "id": "greeting", + "component": { + "Text": { + "text": { "path": "/data/model/userName" }, + "usageHint": "h2" + } + } + }, + { + "id": "status", + "component": { + "Text": { + "text": { "literalString": "Online" }, + "usageHint": "caption" + } + } + } + ] + } +} +``` + +In this example, `greeting` reads the user's name from the data model (updated via `dataModelUpdate`), while `status` uses a hardcoded literal. + +## Handling User Actions + +Interactive components like `Button` trigger `userAction` events that flow back to the server. Each action includes a `name`, the originating `surfaceId` and `sourceComponentId`, and an optional `context` with key-value pairs. + +```json +{ + "userAction": { + "name": "submitForm", + "surfaceId": "form-1", + "sourceComponentId": "submit-btn", + "timestamp": "2026-03-12T10:00:00Z", + "context": { + "selectedOption": "optionA" + } + } +} +``` + +Action context values can also use path bindings to send current data model values back to the server: + +```json +{ + "Button": { + "child": "confirm-label", + "action": { + "name": "confirm", + "context": [ + { + "key": "currentScore", + "value": { "path": "/data/model/score" } + } + ] + } + } +} +``` + +## Validation + +Use `validate_a2ui_message` to validate server-to-client messages and `validate_a2ui_event` for client-to-server events: + +```python Code +from crewai.a2a.extensions.a2ui import validate_a2ui_message +from crewai.a2a.extensions.a2ui.validator import ( + validate_a2ui_event, + A2UIValidationError, +) + +# Validate a server message +try: + msg = validate_a2ui_message({"beginRendering": {"surfaceId": "s1", "root": "r1"}}) +except A2UIValidationError as exc: + print(exc.errors) + +# Validate a client event +try: + event = validate_a2ui_event({ + "userAction": { + "name": "click", + "surfaceId": "s1", + "sourceComponentId": "btn-1", + "timestamp": "2026-03-12T10:00:00Z", + } + }) +except A2UIValidationError as exc: + print(exc.errors) +``` + +## Best Practices + + + + Begin with a `beginRendering` message and a single `surfaceUpdate`. Add data binding and interactivity once the basic flow works. + + + + Prefer path bindings over literal values for content that changes. Use `dataModelUpdate` to push new values without resending the full component tree. + + + + Use the `allowed_components` option on `A2UIClientExtension` to restrict which components the agent may emit, reducing prompt size and keeping output predictable. + + + + Use `validate_a2ui_message` and `validate_a2ui_event` to catch malformed payloads early, especially when building custom integrations. + + + +## Learn More + +- [A2A Agent Delegation](/en/learn/a2a-agent-delegation) — configure agents for remote delegation via the A2A protocol +- [A2A Protocol Documentation](https://a2a-protocol.org) — official protocol specification diff --git a/docs/en/learn/create-custom-tools.mdx b/docs/en/learn/create-custom-tools.mdx index b9d67b49c..c1246f3fc 100644 --- a/docs/en/learn/create-custom-tools.mdx +++ b/docs/en/learn/create-custom-tools.mdx @@ -11,6 +11,10 @@ This guide provides detailed instructions on creating custom tools for the CrewA incorporating the latest functionalities such as tool delegation, error handling, and dynamic tool calling. It also highlights the importance of collaboration tools, enabling agents to perform a wide range of actions. + + **Want to publish your tool for the community?** If you're building a tool that others could benefit from, check out the [Publish Custom Tools](/en/guides/tools/publish-custom-tools) guide to learn how to package and distribute your tool on PyPI. + + ### Subclassing `BaseTool` To create a personalized tool, inherit from `BaseTool` and define the necessary attributes, including the `args_schema` for input validation, and the `_run` method. diff --git a/docs/en/learn/litellm-removal-guide.mdx b/docs/en/learn/litellm-removal-guide.mdx new file mode 100644 index 000000000..4580f7b32 --- /dev/null +++ b/docs/en/learn/litellm-removal-guide.mdx @@ -0,0 +1,358 @@ +--- +title: Using CrewAI Without LiteLLM +description: How to use CrewAI with native provider integrations and remove the LiteLLM dependency from your project. +icon: shield-check +mode: "wide" +--- + +## Overview + +CrewAI supports two paths for connecting to LLM providers: + +1. **Native integrations** — direct SDK connections to OpenAI, Anthropic, Google Gemini, Azure OpenAI, and AWS Bedrock +2. **LiteLLM fallback** — a translation layer that supports 100+ additional providers + +This guide explains how to use CrewAI exclusively with native provider integrations, removing any dependency on LiteLLM. + + + The `litellm` package was quarantined on PyPI due to a security/reliability incident. If you rely on LiteLLM-dependent providers, you should migrate to native integrations. CrewAI's native integrations give you full functionality without LiteLLM. + + +## Why Remove LiteLLM? + +- **Reduced dependency surface** — fewer packages means fewer potential supply-chain risks +- **Better performance** — native SDKs communicate directly with provider APIs, eliminating a translation layer +- **Simpler debugging** — one less abstraction layer between your code and the provider +- **Smaller install footprint** — LiteLLM brings in many transitive dependencies + +## Native Providers (No LiteLLM Required) + +These providers use their own SDKs and work without LiteLLM installed: + + + + GPT-4o, GPT-4o-mini, o1, o3-mini, and more. + ```bash + uv add "crewai[openai]" + ``` + + + Claude Sonnet, Claude Haiku, and more. + ```bash + uv add "crewai[anthropic]" + ``` + + + Gemini 2.0 Flash, Gemini 2.0 Pro, and more. + ```bash + uv add "crewai[gemini]" + ``` + + + Azure-hosted OpenAI models. + ```bash + uv add "crewai[azure]" + ``` + + + Claude, Llama, Titan, and more via AWS. + ```bash + uv add "crewai[bedrock]" + ``` + + + + + If you only use native providers, you **never** need to install `crewai[litellm]`. The base `crewai` package plus your chosen provider extra is all you need. + + +## How to Check If You're Using LiteLLM + +### Check your model strings + +If your code uses model prefixes like these, you're routing through LiteLLM: + +| Prefix | Provider | Uses LiteLLM? | +|--------|----------|---------------| +| `ollama/` | Ollama | ✅ Yes | +| `groq/` | Groq | ✅ Yes | +| `together_ai/` | Together AI | ✅ Yes | +| `mistral/` | Mistral | ✅ Yes | +| `cohere/` | Cohere | ✅ Yes | +| `huggingface/` | Hugging Face | ✅ Yes | +| `openai/` | OpenAI | ❌ Native | +| `anthropic/` | Anthropic | ❌ Native | +| `gemini/` | Google Gemini | ❌ Native | +| `azure/` | Azure OpenAI | ❌ Native | +| `bedrock/` | AWS Bedrock | ❌ Native | + +### Check if LiteLLM is installed + +```bash +# Using pip +pip show litellm + +# Using uv +uv pip show litellm +``` + +If the command returns package information, LiteLLM is installed in your environment. + +### Check your dependencies + +Look at your `pyproject.toml` for `crewai[litellm]`: + +```toml +# If you see this, you have LiteLLM as a dependency +dependencies = [ + "crewai[litellm]>=0.100.0", # ← Uses LiteLLM +] + +# Change to a native provider extra instead +dependencies = [ + "crewai[openai]>=0.100.0", # ← Native, no LiteLLM +] +``` + +## Migration Guide + +### Step 1: Identify your current provider + +Find all `LLM()` calls and model strings in your code: + +```bash +# Search your codebase for LLM model strings +grep -r "LLM(" --include="*.py" . +grep -r "llm=" --include="*.yaml" . +grep -r "llm:" --include="*.yaml" . +``` + +### Step 2: Switch to a native provider + + + + ```python + from crewai import LLM + + # Before (LiteLLM): + # llm = LLM(model="groq/llama-3.1-70b") + + # After (Native): + llm = LLM(model="openai/gpt-4o") + ``` + + ```bash + # Install + uv add "crewai[openai]" + + # Set your API key + export OPENAI_API_KEY="sk-..." + ``` + + + ```python + from crewai import LLM + + # Before (LiteLLM): + # llm = LLM(model="together_ai/meta-llama/Meta-Llama-3.1-70B") + + # After (Native): + llm = LLM(model="anthropic/claude-sonnet-4-20250514") + ``` + + ```bash + # Install + uv add "crewai[anthropic]" + + # Set your API key + export ANTHROPIC_API_KEY="sk-ant-..." + ``` + + + ```python + from crewai import LLM + + # Before (LiteLLM): + # llm = LLM(model="mistral/mistral-large-latest") + + # After (Native): + llm = LLM(model="gemini/gemini-2.0-flash") + ``` + + ```bash + # Install + uv add "crewai[gemini]" + + # Set your API key + export GEMINI_API_KEY="..." + ``` + + + ```python + from crewai import LLM + + # After (Native): + llm = LLM( + model="azure/your-deployment-name", + api_key="your-azure-api-key", + base_url="https://your-resource.openai.azure.com", + api_version="2024-06-01" + ) + ``` + + ```bash + # Install + uv add "crewai[azure]" + ``` + + + ```python + from crewai import LLM + + # After (Native): + llm = LLM( + model="bedrock/anthropic.claude-3-5-sonnet-20241022-v2:0", + aws_region_name="us-east-1" + ) + ``` + + ```bash + # Install + uv add "crewai[bedrock]" + + # Configure AWS credentials + export AWS_ACCESS_KEY_ID="..." + export AWS_SECRET_ACCESS_KEY="..." + export AWS_DEFAULT_REGION="us-east-1" + ``` + + + +### Step 3: Keep Ollama without LiteLLM + +If you're using Ollama and want to keep using it, you can connect via Ollama's OpenAI-compatible API: + +```python +from crewai import LLM + +# Before (LiteLLM): +# llm = LLM(model="ollama/llama3") + +# After (OpenAI-compatible mode, no LiteLLM needed): +llm = LLM( + model="openai/llama3", + base_url="http://localhost:11434/v1", + api_key="ollama" # Ollama doesn't require a real API key +) +``` + + + Many local inference servers (Ollama, vLLM, LM Studio, llama.cpp) expose an OpenAI-compatible API. You can use the `openai/` prefix with a custom `base_url` to connect to any of them natively. + + +### Step 4: Update your YAML configs + +```yaml +# Before (LiteLLM providers): +researcher: + role: Research Specialist + goal: Conduct research + backstory: A dedicated researcher + llm: groq/llama-3.1-70b # ← LiteLLM + +# After (Native provider): +researcher: + role: Research Specialist + goal: Conduct research + backstory: A dedicated researcher + llm: openai/gpt-4o # ← Native +``` + +### Step 5: Remove LiteLLM + +Once you've migrated all your model references: + +```bash +# Remove litellm from your project +uv remove litellm + +# Or if using pip +pip uninstall litellm + +# Update your pyproject.toml: change crewai[litellm] to your provider extra +# e.g., crewai[openai], crewai[anthropic], crewai[gemini] +``` + +### Step 6: Verify + +Run your project and confirm everything works: + +```bash +# Run your crew +crewai run + +# Or run your tests +uv run pytest +``` + +## Quick Reference: Model String Mapping + +Here are common migration paths from LiteLLM-dependent providers to native ones: + +```python +from crewai import LLM + +# ─── LiteLLM providers → Native alternatives ──────────────────── + +# Groq → OpenAI or Anthropic +# llm = LLM(model="groq/llama-3.1-70b") +llm = LLM(model="openai/gpt-4o-mini") # Fast & affordable +llm = LLM(model="anthropic/claude-haiku-3-5") # Fast & affordable + +# Together AI → OpenAI or Gemini +# llm = LLM(model="together_ai/meta-llama/Meta-Llama-3.1-70B") +llm = LLM(model="openai/gpt-4o") # High quality +llm = LLM(model="gemini/gemini-2.0-flash") # Fast & capable + +# Mistral → Anthropic or OpenAI +# llm = LLM(model="mistral/mistral-large-latest") +llm = LLM(model="anthropic/claude-sonnet-4-20250514") # High quality + +# Ollama → OpenAI-compatible (keep using local models) +# llm = LLM(model="ollama/llama3") +llm = LLM( + model="openai/llama3", + base_url="http://localhost:11434/v1", + api_key="ollama" +) +``` + +## FAQ + + + + No, if you use one of the five natively supported providers (OpenAI, Anthropic, Gemini, Azure, Bedrock). These native integrations support all CrewAI features including streaming, tool calling, structured output, and more. You only lose access to providers that are exclusively available through LiteLLM (like Groq, Together AI, Mistral as first-class providers). + + + Yes. Install multiple extras and use different providers for different agents: + ```bash + uv add "crewai[openai,anthropic,gemini]" + ``` + ```python + researcher = Agent(llm="openai/gpt-4o", ...) + writer = Agent(llm="anthropic/claude-sonnet-4-20250514", ...) + ``` + + + Regardless of quarantine status, reducing your dependency surface is good security practice. If you only need providers that CrewAI supports natively, there's no reason to keep LiteLLM installed. + + + Native providers use the same environment variables you're already familiar with. No changes needed for `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GEMINI_API_KEY`, etc. + + + +## Related Resources + +- [LLM Connections](/en/learn/llm-connections) — Full guide to connecting CrewAI with any LLM +- [LLM Concepts](/en/concepts/llms) — Understanding LLMs in CrewAI +- [LLM Selection Guide](/en/learn/llm-selection-guide) — Choosing the right model for your use case diff --git a/docs/en/learn/streaming-crew-execution.mdx b/docs/en/learn/streaming-crew-execution.mdx index bfcd0850d..ff0a3cd7f 100644 --- a/docs/en/learn/streaming-crew-execution.mdx +++ b/docs/en/learn/streaming-crew-execution.mdx @@ -325,6 +325,34 @@ Streaming is particularly valuable for: - **User Experience**: Reduce perceived latency by showing incremental results - **Live Dashboards**: Build monitoring interfaces that display crew execution status +## Cancellation and Resource Cleanup + +`CrewStreamingOutput` supports graceful cancellation so that in-flight work stops promptly when the consumer disconnects. + +### Async Context Manager + +```python Code +streaming = await crew.akickoff(inputs={"topic": "AI"}) + +async with streaming: + async for chunk in streaming: + print(chunk.content, end="", flush=True) +``` + +### Explicit Cancellation + +```python Code +streaming = await crew.akickoff(inputs={"topic": "AI"}) +try: + async for chunk in streaming: + print(chunk.content, end="", flush=True) +finally: + await streaming.aclose() # async + # streaming.close() # sync equivalent +``` + +After cancellation, `streaming.is_cancelled` and `streaming.is_completed` are both `True`. Both `aclose()` and `close()` are idempotent. + ## Important Notes - Streaming automatically enables LLM streaming for all agents in the crew diff --git a/docs/en/learn/streaming-flow-execution.mdx b/docs/en/learn/streaming-flow-execution.mdx index df0fec91d..31ca0f376 100644 --- a/docs/en/learn/streaming-flow-execution.mdx +++ b/docs/en/learn/streaming-flow-execution.mdx @@ -420,6 +420,34 @@ except Exception as e: print("Streaming completed but flow encountered an error") ``` +## Cancellation and Resource Cleanup + +`FlowStreamingOutput` supports graceful cancellation so that in-flight work stops promptly when the consumer disconnects. + +### Async Context Manager + +```python Code +streaming = await flow.kickoff_async() + +async with streaming: + async for chunk in streaming: + print(chunk.content, end="", flush=True) +``` + +### Explicit Cancellation + +```python Code +streaming = await flow.kickoff_async() +try: + async for chunk in streaming: + print(chunk.content, end="", flush=True) +finally: + await streaming.aclose() # async + # streaming.close() # sync equivalent +``` + +After cancellation, `streaming.is_cancelled` and `streaming.is_completed` are both `True`. Both `aclose()` and `close()` are idempotent. + ## Important Notes - Streaming automatically enables LLM streaming for any crews used within the flow diff --git a/docs/en/quickstart.mdx b/docs/en/quickstart.mdx index 0ad5d2612..3b1b76ddf 100644 --- a/docs/en/quickstart.mdx +++ b/docs/en/quickstart.mdx @@ -1,43 +1,49 @@ --- title: Quickstart -description: Build your first AI agent with CrewAI in under 5 minutes. +description: Build your first CrewAI Flow in minutes — orchestration, state, and an agent crew that produces a real report. icon: rocket mode: "wide" --- -## Build your first CrewAI Agent +### Watch: Building CrewAI Agents & Flows with Coding Agent Skills -Let's create a simple crew that will help us `research` and `report` on the `latest AI developments` for a given topic or subject. +Install our coding agent skills (Claude Code, Codex, ...) to quickly get your coding agents up and running with CrewAI. -Before we proceed, make sure you have finished installing CrewAI. -If you haven't installed them yet, you can do so by following the [installation guide](/en/installation). +You can install it with `npx skills add crewaiinc/skills` -Follow the steps below to get Crewing! 🚣‍♂️ + + +In this guide you will **create a Flow** that sets a research topic, runs a **crew with one agent** (a researcher using web search), and ends with a **markdown report** on disk. Flows are the recommended way to structure production apps: they own **state** and **execution order**, while **agents** do the work inside a crew step. + +If you have not installed CrewAI yet, follow the [installation guide](/en/installation) first. + +## Prerequisites + +- Python environment and the CrewAI CLI (see [installation](/en/installation)) +- An LLM configured with the right API keys — see [LLMs](/en/concepts/llms#setting-up-your-llm) +- A [Serper.dev](https://serper.dev/) API key (`SERPER_API_KEY`) for web search in this tutorial + +## Build your first Flow - - Create a new crew project by running the following command in your terminal. - This will create a new directory called `latest-ai-development` with the basic structure for your crew. + + From your terminal, scaffold a Flow project (the folder name uses underscores, e.g. `latest_ai_flow`): + ```shell Terminal - crewai create crew latest-ai-development + crewai create flow latest-ai-flow + cd latest_ai_flow ``` + + This creates a Flow app under `src/latest_ai_flow/`, including a starter crew under `crews/content_crew/` that you will replace with a minimal **single-agent** research crew in the next steps. - - - ```shell Terminal - cd latest_ai_development - ``` - - - - - You can also modify the agents as needed to fit your use case or copy and paste as is to your project. - Any variable interpolated in your `agents.yaml` and `tasks.yaml` files like `{topic}` will be replaced by the value of the variable in the `main.py` file. - + + + Replace the contents of `src/latest_ai_flow/crews/content_crew/config/agents.yaml` with a single researcher. Variables like `{topic}` are filled from `crew.kickoff(inputs=...)`. + ```yaml agents.yaml - # src/latest_ai_development/config/agents.yaml + # src/latest_ai_flow/crews/content_crew/config/agents.yaml researcher: role: > {topic} Senior Data Researcher @@ -45,336 +51,232 @@ Follow the steps below to get Crewing! 🚣‍♂️ Uncover cutting-edge developments in {topic} backstory: > You're a seasoned researcher with a knack for uncovering the latest - developments in {topic}. Known for your ability to find the most relevant - information and present it in a clear and concise manner. - - reporting_analyst: - role: > - {topic} Reporting Analyst - goal: > - Create detailed reports based on {topic} data analysis and research findings - backstory: > - You're a meticulous analyst with a keen eye for detail. You're known for - your ability to turn complex data into clear and concise reports, making - it easy for others to understand and act on the information you provide. + developments in {topic}. You find the most relevant information and + present it clearly. ``` - + + ```yaml tasks.yaml - # src/latest_ai_development/config/tasks.yaml + # src/latest_ai_flow/crews/content_crew/config/tasks.yaml research_task: description: > - Conduct a thorough research about {topic} - Make sure you find any interesting and relevant information given - the current year is 2025. + Conduct thorough research about {topic}. Use web search to find current, + credible information. The current year is 2026. expected_output: > - A list with 10 bullet points of the most relevant information about {topic} + A markdown report with clear sections: key trends, notable tools or companies, + and implications. Aim for 800–1200 words. No fenced code blocks around the whole document. agent: researcher - - reporting_task: - description: > - Review the context you got and expand each topic into a full section for a report. - Make sure the report is detailed and contains any and all relevant information. - expected_output: > - A fully fledge reports with the mains topics, each with a full section of information. - Formatted as markdown without '```' - agent: reporting_analyst - output_file: report.md + output_file: output/report.md ``` - - ```python crew.py - # src/latest_ai_development/crew.py - from crewai import Agent, Crew, Process, Task - from crewai.project import CrewBase, agent, crew, task - from crewai_tools import SerperDevTool - from crewai.agents.agent_builder.base_agent import BaseAgent + + + Point the generated crew at your YAML and attach `SerperDevTool` to the researcher. + + ```python content_crew.py + # src/latest_ai_flow/crews/content_crew/content_crew.py from typing import List + from crewai import Agent, Crew, Process, Task + from crewai.agents.agent_builder.base_agent import BaseAgent + from crewai.project import CrewBase, agent, crew, task + from crewai_tools import SerperDevTool + + @CrewBase - class LatestAiDevelopmentCrew(): - """LatestAiDevelopment crew""" + class ResearchCrew: + """Single-agent research crew used inside the Flow.""" agents: List[BaseAgent] tasks: List[Task] + agents_config = "config/agents.yaml" + tasks_config = "config/tasks.yaml" + @agent def researcher(self) -> Agent: return Agent( - config=self.agents_config['researcher'], # type: ignore[index] + config=self.agents_config["researcher"], # type: ignore[index] verbose=True, - tools=[SerperDevTool()] - ) - - @agent - def reporting_analyst(self) -> Agent: - return Agent( - config=self.agents_config['reporting_analyst'], # type: ignore[index] - verbose=True + tools=[SerperDevTool()], ) @task def research_task(self) -> Task: return Task( - config=self.tasks_config['research_task'], # type: ignore[index] - ) - - @task - def reporting_task(self) -> Task: - return Task( - config=self.tasks_config['reporting_task'], # type: ignore[index] - output_file='output/report.md' # This is the file that will be contain the final report. + config=self.tasks_config["research_task"], # type: ignore[index] ) @crew def crew(self) -> Crew: - """Creates the LatestAiDevelopment crew""" return Crew( - agents=self.agents, # Automatically created by the @agent decorator - tasks=self.tasks, # Automatically created by the @task decorator + agents=self.agents, + tasks=self.tasks, process=Process.sequential, verbose=True, ) ``` - - ```python crew.py - # src/latest_ai_development/crew.py - from crewai import Agent, Crew, Process, Task - from crewai.project import CrewBase, agent, crew, task, before_kickoff, after_kickoff - from crewai_tools import SerperDevTool - @CrewBase - class LatestAiDevelopmentCrew(): - """LatestAiDevelopment crew""" + + Connect the crew to a Flow: a `@start()` step sets the topic in **state**, and a `@listen` step runs the crew. The task’s `output_file` still writes `output/report.md`. - @before_kickoff - def before_kickoff_function(self, inputs): - print(f"Before kickoff function with inputs: {inputs}") - return inputs # You can return the inputs or modify them as needed - - @after_kickoff - def after_kickoff_function(self, result): - print(f"After kickoff function with result: {result}") - return result # You can return the result or modify it as needed - - # ... remaining code - ``` - - - - For example, you can pass the `topic` input to your crew to customize the research and reporting. ```python main.py - #!/usr/bin/env python - # src/latest_ai_development/main.py - import sys - from latest_ai_development.crew import LatestAiDevelopmentCrew + # src/latest_ai_flow/main.py + from pydantic import BaseModel - def run(): - """ - Run the crew. - """ - inputs = { - 'topic': 'AI Agents' - } - LatestAiDevelopmentCrew().crew().kickoff(inputs=inputs) + from crewai.flow import Flow, listen, start + + from latest_ai_flow.crews.content_crew.content_crew import ResearchCrew + + + class ResearchFlowState(BaseModel): + topic: str = "" + report: str = "" + + + class LatestAiFlow(Flow[ResearchFlowState]): + @start() + def prepare_topic(self, crewai_trigger_payload: dict | None = None): + if crewai_trigger_payload: + self.state.topic = crewai_trigger_payload.get("topic", "AI Agents") + else: + self.state.topic = "AI Agents" + print(f"Topic: {self.state.topic}") + + @listen(prepare_topic) + def run_research(self): + result = ResearchCrew().crew().kickoff(inputs={"topic": self.state.topic}) + self.state.report = result.raw + print("Research crew finished.") + + @listen(run_research) + def summarize(self): + print("Report path: output/report.md") + + + def kickoff(): + LatestAiFlow().kickoff() + + + def plot(): + LatestAiFlow().plot() + + + if __name__ == "__main__": + kickoff() ``` - - - Before running your crew, make sure you have the following keys set as environment variables in your `.env` file: - - A [Serper.dev](https://serper.dev/) API key: `SERPER_API_KEY=YOUR_KEY_HERE` - - The configuration for your choice of model, such as an API key. See the - [LLM setup guide](/en/concepts/llms#setting-up-your-llm) to learn how to configure models from any provider. - - - - Lock the dependencies and install them by using the CLI command: - - ```shell Terminal - crewai install - ``` - - - If you have additional packages that you want to install, you can do so by running: - - ```shell Terminal - uv add - ``` - - - - - To run your crew, execute the following command in the root of your project: - - ```bash Terminal - crewai run - ``` - + + If your package name differs from `latest_ai_flow`, change the import of `ResearchCrew` to match your project’s module path. + - - For CrewAI AMP users, you can create the same crew without writing code: + + In `.env` at the project root, set: -1. Log in to your CrewAI AMP account (create a free account at [app.crewai.com](https://app.crewai.com)) -2. Open Crew Studio -3. Type what is the automation you're trying to build -4. Create your tasks visually and connect them in sequence -5. Configure your inputs and click "Download Code" or "Deploy" - -![Crew Studio Quickstart](/images/enterprise/crew-studio-interface.png) - - - Start your free account at CrewAI AMP - + - `SERPER_API_KEY` — from [Serper.dev](https://serper.dev/) + - Your model provider keys as required — see [LLM setup](/en/concepts/llms#setting-up-your-llm) - - You should see the output in the console and the `report.md` file should be created in the root of your project with the final report. -Here's an example of what the report should look like: + + + ```shell Terminal + crewai install + crewai run + ``` + + + `crewai run` executes the Flow entrypoint defined in your project (same command as for crews; project type is `"flow"` in `pyproject.toml`). + + + + + + + You should see logs from the Flow and the crew. Open **`output/report.md`** for the generated report (excerpt): ```markdown output/report.md - # Comprehensive Report on the Rise and Impact of AI Agents in 2025 + # AI Agents in 2026: Landscape and Trends - ## 1. Introduction to AI Agents - In 2025, Artificial Intelligence (AI) agents are at the forefront of innovation across various industries. As intelligent systems that can perform tasks typically requiring human cognition, AI agents are paving the way for significant advancements in operational efficiency, decision-making, and overall productivity within sectors like Human Resources (HR) and Finance. This report aims to detail the rise of AI agents, their frameworks, applications, and potential implications on the workforce. + ## Executive summary + … - ## 2. Benefits of AI Agents - AI agents bring numerous advantages that are transforming traditional work environments. Key benefits include: + ## Key trends + - **Tool use and orchestration** — … + - **Enterprise adoption** — … - - **Task Automation**: AI agents can carry out repetitive tasks such as data entry, scheduling, and payroll processing without human intervention, greatly reducing the time and resources spent on these activities. - - **Improved Efficiency**: By quickly processing large datasets and performing analyses that would take humans significantly longer, AI agents enhance operational efficiency. This allows teams to focus on strategic tasks that require higher-level thinking. - - **Enhanced Decision-Making**: AI agents can analyze trends and patterns in data, provide insights, and even suggest actions, helping stakeholders make informed decisions based on factual data rather than intuition alone. - - ## 3. Popular AI Agent Frameworks - Several frameworks have emerged to facilitate the development of AI agents, each with its own unique features and capabilities. Some of the most popular frameworks include: - - - **Autogen**: A framework designed to streamline the development of AI agents through automation of code generation. - - **Semantic Kernel**: Focuses on natural language processing and understanding, enabling agents to comprehend user intentions better. - - **Promptflow**: Provides tools for developers to create conversational agents that can navigate complex interactions seamlessly. - - **Langchain**: Specializes in leveraging various APIs to ensure agents can access and utilize external data effectively. - - **CrewAI**: Aimed at collaborative environments, CrewAI strengthens teamwork by facilitating communication through AI-driven insights. - - **MemGPT**: Combines memory-optimized architectures with generative capabilities, allowing for more personalized interactions with users. - - These frameworks empower developers to build versatile and intelligent agents that can engage users, perform advanced analytics, and execute various tasks aligned with organizational goals. - - ## 4. AI Agents in Human Resources - AI agents are revolutionizing HR practices by automating and optimizing key functions: - - - **Recruiting**: AI agents can screen resumes, schedule interviews, and even conduct initial assessments, thus accelerating the hiring process while minimizing biases. - - **Succession Planning**: AI systems analyze employee performance data and potential, helping organizations identify future leaders and plan appropriate training. - - **Employee Engagement**: Chatbots powered by AI can facilitate feedback loops between employees and management, promoting an open culture and addressing concerns promptly. - - As AI continues to evolve, HR departments leveraging these agents can realize substantial improvements in both efficiency and employee satisfaction. - - ## 5. AI Agents in Finance - The finance sector is seeing extensive integration of AI agents that enhance financial practices: - - - **Expense Tracking**: Automated systems manage and monitor expenses, flagging anomalies and offering recommendations based on spending patterns. - - **Risk Assessment**: AI models assess credit risk and uncover potential fraud by analyzing transaction data and behavioral patterns. - - **Investment Decisions**: AI agents provide stock predictions and analytics based on historical data and current market conditions, empowering investors with informative insights. - - The incorporation of AI agents into finance is fostering a more responsive and risk-aware financial landscape. - - ## 6. Market Trends and Investments - The growth of AI agents has attracted significant investment, especially amidst the rising popularity of chatbots and generative AI technologies. Companies and entrepreneurs are eager to explore the potential of these systems, recognizing their ability to streamline operations and improve customer engagement. - - Conversely, corporations like Microsoft are taking strides to integrate AI agents into their product offerings, with enhancements to their Copilot 365 applications. This strategic move emphasizes the importance of AI literacy in the modern workplace and indicates the stabilizing of AI agents as essential business tools. - - ## 7. Future Predictions and Implications - Experts predict that AI agents will transform essential aspects of work life. As we look toward the future, several anticipated changes include: - - - Enhanced integration of AI agents across all business functions, creating interconnected systems that leverage data from various departmental silos for comprehensive decision-making. - - Continued advancement of AI technologies, resulting in smarter, more adaptable agents capable of learning and evolving from user interactions. - - Increased regulatory scrutiny to ensure ethical use, especially concerning data privacy and employee surveillance as AI agents become more prevalent. - - To stay competitive and harness the full potential of AI agents, organizations must remain vigilant about latest developments in AI technology and consider continuous learning and adaptation in their strategic planning. - - ## 8. Conclusion - The emergence of AI agents is undeniably reshaping the workplace landscape in 5. With their ability to automate tasks, enhance efficiency, and improve decision-making, AI agents are critical in driving operational success. Organizations must embrace and adapt to AI developments to thrive in an increasingly digital business environment. + ## Implications + … ``` - + + Your actual file will be longer and reflect live search results. +## How this run fits together + +1. **Flow** — `LatestAiFlow` runs `prepare_topic` first, then `run_research`, then `summarize`. State (`topic`, `report`) lives on the Flow. +2. **Crew** — `ResearchCrew` runs one task with one agent: the researcher uses **Serper** to search the web, then writes the structured report. +3. **Artifact** — The task’s `output_file` writes the report under `output/report.md`. + +To go deeper on Flow patterns (routing, persistence, human-in-the-loop), see [Build your first Flow](/en/guides/flows/first-flow) and [Flows](/en/concepts/flows). For crews without a Flow, see [Crews](/en/concepts/crews). For a single `Agent` and `kickoff()` without tasks, see [Agents](/en/concepts/agents#direct-agent-interaction-with-kickoff). + -Congratulations! - -You have successfully set up your crew project and are ready to start building your own agentic workflows! - +You now have an end-to-end Flow with an agent crew and a saved report — a solid base to add more steps, crews, or tools. -### Note on Consistency in Naming +### Naming consistency -The names you use in your YAML files (`agents.yaml` and `tasks.yaml`) should match the method names in your Python code. -For example, you can reference the agent for specific tasks from `tasks.yaml` file. -This naming consistency allows CrewAI to automatically link your configurations with your code; otherwise, your task won't recognize the reference properly. +YAML keys (`researcher`, `research_task`) must match the method names on your `@CrewBase` class. See [Crews](/en/concepts/crews) for the full decorator pattern. -#### Example References +## Deploying - - Note how we use the same name for the agent in the `agents.yaml` - (`email_summarizer`) file as the method name in the `crew.py` - (`email_summarizer`) file. - +Push your Flow to **[CrewAI AMP](https://app.crewai.com)** once it runs locally and your project is in a **GitHub** repository. From the project root: -```yaml agents.yaml -email_summarizer: - role: > - Email Summarizer - goal: > - Summarize emails into a concise and clear summary - backstory: > - You will create a 5 bullet point summary of the report - llm: provider/model-id # Add your choice of model here + +```bash Authenticate +crewai login ``` - - Note how we use the same name for the task in the `tasks.yaml` - (`email_summarizer_task`) file as the method name in the `crew.py` - (`email_summarizer_task`) file. - - -```yaml tasks.yaml -email_summarizer_task: - description: > - Summarize the email into a 5 bullet point summary - expected_output: > - A 5 bullet point summary of the email - agent: email_summarizer - context: - - reporting_task - - research_task +```bash Create deployment +crewai deploy create ``` -## Deploying Your Crew +```bash Check status & logs +crewai deploy status +crewai deploy logs +``` -The easiest way to deploy your crew to production is through [CrewAI AMP](http://app.crewai.com). +```bash Ship updates after you change code +crewai deploy push +``` -Watch this video tutorial for a step-by-step demonstration of deploying your crew to [CrewAI AMP](http://app.crewai.com) using the CLI. +```bash List or remove deployments +crewai deploy list +crewai deploy remove +``` + - + + The first deploy usually takes **around 1 minute**. Full prerequisites and the web UI flow are in [Deploy to AMP](/en/enterprise/guides/deploy-to-amp). + - - Get started with CrewAI AMP and deploy your crew in a production environment - with just a few clicks. + + Step-by-step AMP deployment (CLI and dashboard). - Join our open source community to discuss ideas, share your projects, and - connect with other CrewAI developers. + Discuss ideas, share projects, and connect with other CrewAI developers. diff --git a/docs/en/skills.mdx b/docs/en/skills.mdx new file mode 100644 index 000000000..81260c88f --- /dev/null +++ b/docs/en/skills.mdx @@ -0,0 +1,50 @@ +--- +title: Skills +description: Install crewaiinc/skills from the official registry at skills.sh—Flows, Crews, and docs-aware agents for Claude Code, Cursor, Codex, and more. +icon: wand-magic-sparkles +mode: "wide" +--- + +# Skills + +**Give your AI coding agent CrewAI context in one command.** + +CrewAI **Skills** are published on **[skills.sh/crewaiinc/skills](https://skills.sh/crewaiinc/skills)**—the official registry for `crewaiinc/skills`, including individual skills (for example **design-agent**, **getting-started**, **design-task**, and **ask-docs**), install stats, and audits. They teach coding agents—like Claude Code, Cursor, and Codex—how to scaffold Flows, configure Crews, use tools, and follow CrewAI patterns. Run the install below (or paste it into your agent). + +```shell Terminal +npx skills add crewaiinc/skills +``` + +That pulls the official skill pack into your agent workflow so it can apply CrewAI conventions without you re-explaining the framework each session. Source code and issues live on [GitHub](https://github.com/crewAIInc/skills). + +## What your agent gets + +- **Flows** — structure stateful apps, steps, and crew kickoffs the CrewAI way +- **Crews & agents** — YAML-first patterns, roles, tasks, and delegation +- **Tools & integrations** — hook agents to search, APIs, and common CrewAI tools +- **Project layout** — align with CLI scaffolds and repo conventions +- **Up-to-date patterns** — skills track current CrewAI docs and recommended practices + +## Learn more on this site + + + + How to use `AGENTS.md` and coding-agent workflows with CrewAI. + + + Build your first Flow and crew end-to-end. + + + Install the CrewAI CLI and Python package. + + + Official listing for `crewaiinc/skills`—skills, installs, and audits. + + + Source, updates, and issues for the skill pack. + + + +### Video: CrewAI with coding agent skills + + + ## 비디오 튜토리얼 설치 과정을 단계별로 시연하는 비디오 튜토리얼을 시청하세요: @@ -189,9 +197,8 @@ CrewAI는 의존성 관리와 패키지 처리를 위해 `uv`를 사용합니다 ## 다음 단계 - - 빠른 시작 가이드를 따라 CrewAI 에이전트를 처음 만들어보고 직접 경험해 - 보세요. + + Flow를 만들고 에이전트 한 명짜리 crew를 실행해 보고서까지 만드는 방법을 따라 해 보세요. + ## CrewAI 아키텍처 CrewAI의 아키텍처는 자율성과 제어의 균형을 맞추도록 설계되었습니다. @@ -130,9 +138,9 @@ Crews의 기능: - 빠른 시작 가이드를 따라 첫 번째 CrewAI agent를 만들고 직접 경험해 보세요. + Flow를 만들고 에이전트 한 명 crew를 실행해 끝까지 보고서를 생성해 보세요. + **커뮤니티에 도구를 배포하고 싶으신가요?** 다른 사용자에게도 유용한 도구를 만들고 있다면, [커스텀 도구 배포하기](/ko/guides/tools/publish-custom-tools) 가이드에서 도구를 패키징하고 PyPI에 배포하는 방법을 알아보세요. + + ### `BaseTool` 서브클래싱 개인화된 툴을 생성하려면 `BaseTool`을 상속받고, 입력 검증을 위한 `args_schema`와 `_run` 메서드를 포함한 필요한 속성들을 정의해야 합니다. diff --git a/docs/ko/learn/streaming-crew-execution.mdx b/docs/ko/learn/streaming-crew-execution.mdx index aec56caed..db2ce1c0c 100644 --- a/docs/ko/learn/streaming-crew-execution.mdx +++ b/docs/ko/learn/streaming-crew-execution.mdx @@ -325,6 +325,34 @@ asyncio.run(interactive_research()) - **사용자 경험**: 점진적인 결과를 표시하여 체감 지연 시간 감소 - **라이브 대시보드**: crew 실행 상태를 표시하는 모니터링 인터페이스 구축 +## 취소 및 리소스 정리 + +`CrewStreamingOutput`은 소비자가 연결을 끊을 때 진행 중인 작업을 즉시 중단하는 정상적인 취소를 지원합니다. + +### 비동기 컨텍스트 매니저 + +```python Code +streaming = await crew.akickoff(inputs={"topic": "AI"}) + +async with streaming: + async for chunk in streaming: + print(chunk.content, end="", flush=True) +``` + +### 명시적 취소 + +```python Code +streaming = await crew.akickoff(inputs={"topic": "AI"}) +try: + async for chunk in streaming: + print(chunk.content, end="", flush=True) +finally: + await streaming.aclose() # 비동기 + # streaming.close() # 동기 버전 +``` + +취소 후 `streaming.is_cancelled`와 `streaming.is_completed`는 모두 `True`입니다. `aclose()`와 `close()` 모두 멱등성을 가집니다. + ## 중요 사항 - 스트리밍은 crew의 모든 에이전트에 대해 자동으로 LLM 스트리밍을 활성화합니다 diff --git a/docs/ko/quickstart.mdx b/docs/ko/quickstart.mdx index cdfbf6608..cf62097d0 100644 --- a/docs/ko/quickstart.mdx +++ b/docs/ko/quickstart.mdx @@ -1,379 +1,278 @@ --- title: 퀵스타트 -description: 5분 이내에 CrewAI로 첫 번째 AI 에이전트를 구축해보세요. +description: 몇 분 안에 첫 CrewAI Flow를 만듭니다 — 오케스트레이션, 상태, 그리고 실제 보고서를 만드는 에이전트 crew까지. icon: rocket mode: "wide" --- -## 첫 번째 CrewAI Agent 만들기 +### 영상: 코딩 에이전트 스킬을 활용한 CrewAI Agents & Flows 구축 -이제 주어진 주제나 항목에 대해 `최신 AI 개발 동향`을 `연구`하고 `보고`하는 간단한 crew를 만들어보겠습니다. +코딩 에이전트 스킬(Claude Code, Codex 등)을 설치하여 CrewAI로 코딩 에이전트를 빠르게 시작하세요. -진행하기 전에 CrewAI 설치를 완료했는지 확인하세요. -아직 설치하지 않았다면, [설치 가이드](/ko/installation)를 참고해 설치할 수 있습니다. +`npx skills add crewaiinc/skills` 명령어로 설치할 수 있습니다 -아래 단계를 따라 Crewing을 시작하세요! 🚣‍♂️ + + +이 가이드에서는 **Flow**를 만들어 연구 주제를 정하고, **에이전트 한 명으로 구성된 crew**(웹 검색을 쓰는 연구원)를 실행한 뒤, 디스크에 **Markdown 보고서**를 남깁니다. Flow는 프로덕션 앱을 구성하는 권장 방식으로, **상태**와 **실행 순서**를 담당하고 **에이전트**는 crew 단계 안에서 실제 작업을 수행합니다. + +CrewAI를 아직 설치하지 않았다면 먼저 [설치 가이드](/ko/installation)를 따르세요. + +## 사전 요건 + +- Python 환경과 CrewAI CLI([설치](/ko/installation) 참고) +- 올바른 API 키로 설정한 LLM — [LLM](/ko/concepts/llms#setting-up-your-llm) 참고 +- 이 튜토리얼의 웹 검색용 [Serper.dev](https://serper.dev/) API 키(`SERPER_API_KEY`) + +## 첫 번째 Flow 만들기 - - 터미널에서 아래 명령어를 실행하여 새로운 crew 프로젝트를 만드세요. - 이 작업은 `latest-ai-development`라는 새 디렉터리와 기본 구조를 생성합니다. + + 터미널에서 Flow 프로젝트를 생성합니다(폴더 이름은 밑줄 형식입니다. 예: `latest_ai_flow`). + ```shell Terminal - crewai create crew latest-ai-development + crewai create flow latest-ai-flow + cd latest_ai_flow ``` + + 이렇게 하면 `src/latest_ai_flow/` 아래에 Flow 앱이 만들어지고, 다음 단계에서 **단일 에이전트** 연구 crew로 바꿀 시작용 crew가 `crews/content_crew/`에 포함됩니다. - - - ```shell Terminal - cd latest_ai_development - ``` - - - - - 프로젝트에 맞게 agent를 수정하거나 복사/붙여넣기를 할 수 있습니다. - `agents.yaml` 및 `tasks.yaml` 파일에서 `{topic}`과 같은 변수를 사용하면, 이는 `main.py` 파일의 변수 값으로 대체됩니다. - + + + `src/latest_ai_flow/crews/content_crew/config/agents.yaml` 내용을 한 명의 연구원만 남기도록 바꿉니다. `{topic}` 같은 변수는 `crew.kickoff(inputs=...)`로 채워집니다. + ```yaml agents.yaml - # src/latest_ai_development/config/agents.yaml + # src/latest_ai_flow/crews/content_crew/config/agents.yaml researcher: role: > - {topic} Senior Data Researcher + {topic} 시니어 데이터 리서처 goal: > - Uncover cutting-edge developments in {topic} + {topic} 분야의 최신 동향을 파악한다 backstory: > - You're a seasoned researcher with a knack for uncovering the latest - developments in {topic}. Known for your ability to find the most relevant - information and present it in a clear and concise manner. - - reporting_analyst: - role: > - {topic} Reporting Analyst - goal: > - Create detailed reports based on {topic} data analysis and research findings - backstory: > - You're a meticulous analyst with a keen eye for detail. You're known for - your ability to turn complex data into clear and concise reports, making - it easy for others to understand and act on the information you provide. + 당신은 {topic}의 최신 흐름을 찾아내는 데 능숙한 연구원입니다. + 가장 관련성 높은 정보를 찾아 명확하게 전달합니다. ``` - + + ```yaml tasks.yaml - # src/latest_ai_development/config/tasks.yaml + # src/latest_ai_flow/crews/content_crew/config/tasks.yaml research_task: description: > - Conduct a thorough research about {topic} - Make sure you find any interesting and relevant information given - the current year is 2025. + {topic}에 대해 철저히 조사하세요. 웹 검색으로 최신이고 신뢰할 수 있는 정보를 찾으세요. + 현재 연도는 2026년입니다. expected_output: > - A list with 10 bullet points of the most relevant information about {topic} + 마크다운 보고서로, 주요 트렌드·주목할 도구나 기업·시사점 등으로 섹션을 나누세요. + 분량은 약 800~1200단어. 문서 전체를 코드 펜스로 감싸지 마세요. agent: researcher - - reporting_task: - description: > - Review the context you got and expand each topic into a full section for a report. - Make sure the report is detailed and contains any and all relevant information. - expected_output: > - A fully fledge reports with the mains topics, each with a full section of information. - Formatted as markdown without '```' - agent: reporting_analyst - output_file: report.md + output_file: output/report.md ``` - - ```python crew.py - # src/latest_ai_development/crew.py - from crewai import Agent, Crew, Process, Task - from crewai.project import CrewBase, agent, crew, task - from crewai_tools import SerperDevTool - from crewai.agents.agent_builder.base_agent import BaseAgent + + + 생성된 crew가 YAML을 읽고 연구원에게 `SerperDevTool`을 붙이도록 합니다. + + ```python content_crew.py + # src/latest_ai_flow/crews/content_crew/content_crew.py from typing import List + from crewai import Agent, Crew, Process, Task + from crewai.agents.agent_builder.base_agent import BaseAgent + from crewai.project import CrewBase, agent, crew, task + from crewai_tools import SerperDevTool + + @CrewBase - class LatestAiDevelopmentCrew(): - """LatestAiDevelopment crew""" + class ResearchCrew: + """Flow 안에서 사용하는 단일 에이전트 연구 crew.""" agents: List[BaseAgent] tasks: List[Task] + agents_config = "config/agents.yaml" + tasks_config = "config/tasks.yaml" + @agent def researcher(self) -> Agent: return Agent( - config=self.agents_config['researcher'], # type: ignore[index] + config=self.agents_config["researcher"], # type: ignore[index] verbose=True, - tools=[SerperDevTool()] - ) - - @agent - def reporting_analyst(self) -> Agent: - return Agent( - config=self.agents_config['reporting_analyst'], # type: ignore[index] - verbose=True + tools=[SerperDevTool()], ) @task def research_task(self) -> Task: return Task( - config=self.tasks_config['research_task'], # type: ignore[index] - ) - - @task - def reporting_task(self) -> Task: - return Task( - config=self.tasks_config['reporting_task'], # type: ignore[index] - output_file='output/report.md' # This is the file that will be contain the final report. + config=self.tasks_config["research_task"], # type: ignore[index] ) @crew def crew(self) -> Crew: - """Creates the LatestAiDevelopment crew""" return Crew( - agents=self.agents, # Automatically created by the @agent decorator - tasks=self.tasks, # Automatically created by the @task decorator + agents=self.agents, + tasks=self.tasks, process=Process.sequential, verbose=True, ) ``` - - ```python crew.py - # src/latest_ai_development/crew.py - from crewai import Agent, Crew, Process, Task - from crewai.project import CrewBase, agent, crew, task, before_kickoff, after_kickoff - from crewai_tools import SerperDevTool - @CrewBase - class LatestAiDevelopmentCrew(): - """LatestAiDevelopment crew""" + + crew를 Flow에 연결합니다: `@start()` 단계에서 주제를 **상태**에 넣고, `@listen` 단계에서 crew를 실행합니다. 작업의 `output_file`은 그대로 `output/report.md`에 씁니다. - @before_kickoff - def before_kickoff_function(self, inputs): - print(f"Before kickoff function with inputs: {inputs}") - return inputs # You can return the inputs or modify them as needed - - @after_kickoff - def after_kickoff_function(self, result): - print(f"After kickoff function with result: {result}") - return result # You can return the result or modify it as needed - - # ... remaining code - ``` - - - - 예를 들어, crew에 `topic` 입력값을 넘겨 연구 및 보고서 출력을 맞춤화할 수 있습니다. ```python main.py - #!/usr/bin/env python - # src/latest_ai_development/main.py - import sys - from latest_ai_development.crew import LatestAiDevelopmentCrew + # src/latest_ai_flow/main.py + from pydantic import BaseModel - def run(): - """ - Run the crew. - """ - inputs = { - 'topic': 'AI Agents' - } - LatestAiDevelopmentCrew().crew().kickoff(inputs=inputs) + from crewai.flow import Flow, listen, start + + from latest_ai_flow.crews.content_crew.content_crew import ResearchCrew + + + class ResearchFlowState(BaseModel): + topic: str = "" + report: str = "" + + + class LatestAiFlow(Flow[ResearchFlowState]): + @start() + def prepare_topic(self, crewai_trigger_payload: dict | None = None): + if crewai_trigger_payload: + self.state.topic = crewai_trigger_payload.get("topic", "AI Agents") + else: + self.state.topic = "AI Agents" + print(f"주제: {self.state.topic}") + + @listen(prepare_topic) + def run_research(self): + result = ResearchCrew().crew().kickoff(inputs={"topic": self.state.topic}) + self.state.report = result.raw + print("연구 crew 실행 완료.") + + @listen(run_research) + def summarize(self): + print("보고서 경로: output/report.md") + + + def kickoff(): + LatestAiFlow().kickoff() + + + def plot(): + LatestAiFlow().plot() + + + if __name__ == "__main__": + kickoff() ``` - - - crew를 실행하기 전에 `.env` 파일에 아래 키가 환경 변수로 설정되어 있는지 확인하세요: - - [Serper.dev](https://serper.dev/) API 키: `SERPER_API_KEY=YOUR_KEY_HERE` - - 사용하려는 모델의 설정, 예: API 키. 다양한 공급자의 모델 설정은 - [LLM 설정 가이드](/ko/concepts/llms#setting-up-your-llm)를 참고하세요. - - - - CLI 명령어로 의존성을 잠그고 설치하세요: - - ```shell Terminal - crewai install - ``` - - - 추가 설치가 필요한 패키지가 있다면, 아래와 같이 실행하면 됩니다: - - ```shell Terminal - uv add - ``` - - - - - 프로젝트 루트에서 다음 명령어로 crew를 실행하세요: - - ```bash Terminal - crewai run - ``` - + + 패키지 이름이 `latest_ai_flow`가 아니면 `ResearchCrew` import 경로를 프로젝트 모듈 경로에 맞게 바꾸세요. + - - CrewAI AMP 사용자는 코드를 작성하지 않고도 동일한 crew를 생성할 수 있습니다: + + 프로젝트 루트의 `.env`에 다음을 설정합니다. -1. CrewAI AMP 계정에 로그인하세요([app.crewai.com](https://app.crewai.com)에서 무료 계정 만들기) -2. Crew Studio 열기 -3. 구현하려는 자동화 내용을 입력하세요 -4. 미션을 시각적으로 생성하고 순차적으로 연결하세요 -5. 입력값을 구성하고 "Download Code" 또는 "Deploy"를 클릭하세요 - -![Crew Studio Quickstart](/images/enterprise/crew-studio-interface.png) - - - CrewAI AOP에서 무료 계정을 시작하세요 - + - `SERPER_API_KEY` — [Serper.dev](https://serper.dev/)에서 발급 + - 모델 제공자 키 — [LLM 설정](/ko/concepts/llms#setting-up-your-llm) 참고 - - 콘솔에서 출력 결과를 확인할 수 있으며 프로젝트 루트에 `report.md` 파일로 최종 보고서가 생성됩니다. -보고서 예시는 다음과 같습니다: + + + ```shell Terminal + crewai install + crewai run + ``` + + + `crewai run`은 프로젝트에 정의된 Flow 진입점을 실행합니다(crew와 동일한 명령이며, `pyproject.toml`의 프로젝트 유형은 `"flow"`입니다). + + + + Flow와 crew 로그가 출력되어야 합니다. 생성된 보고서는 **`output/report.md`**에서 확인하세요(발췌): ```markdown output/report.md - # Comprehensive Report on the Rise and Impact of AI Agents in 2025 + # 2026년 AI 에이전트: 동향과 전망 - ## 1. Introduction to AI Agents - In 2025, Artificial Intelligence (AI) agents are at the forefront of innovation across various industries. As intelligent systems that can perform tasks typically requiring human cognition, AI agents are paving the way for significant advancements in operational efficiency, decision-making, and overall productivity within sectors like Human Resources (HR) and Finance. This report aims to detail the rise of AI agents, their frameworks, applications, and potential implications on the workforce. + ## 요약 + … - ## 2. Benefits of AI Agents - AI agents bring numerous advantages that are transforming traditional work environments. Key benefits include: + ## 주요 트렌드 + - **도구 사용과 오케스트레이션** — … + - **엔터프라이즈 도입** — … - - **Task Automation**: AI agents can carry out repetitive tasks such as data entry, scheduling, and payroll processing without human intervention, greatly reducing the time and resources spent on these activities. - - **Improved Efficiency**: By quickly processing large datasets and performing analyses that would take humans significantly longer, AI agents enhance operational efficiency. This allows teams to focus on strategic tasks that require higher-level thinking. - - **Enhanced Decision-Making**: AI agents can analyze trends and patterns in data, provide insights, and even suggest actions, helping stakeholders make informed decisions based on factual data rather than intuition alone. - - ## 3. Popular AI Agent Frameworks - Several frameworks have emerged to facilitate the development of AI agents, each with its own unique features and capabilities. Some of the most popular frameworks include: - - - **Autogen**: A framework designed to streamline the development of AI agents through automation of code generation. - - **Semantic Kernel**: Focuses on natural language processing and understanding, enabling agents to comprehend user intentions better. - - **Promptflow**: Provides tools for developers to create conversational agents that can navigate complex interactions seamlessly. - - **Langchain**: Specializes in leveraging various APIs to ensure agents can access and utilize external data effectively. - - **CrewAI**: Aimed at collaborative environments, CrewAI strengthens teamwork by facilitating communication through AI-driven insights. - - **MemGPT**: Combines memory-optimized architectures with generative capabilities, allowing for more personalized interactions with users. - - These frameworks empower developers to build versatile and intelligent agents that can engage users, perform advanced analytics, and execute various tasks aligned with organizational goals. - - ## 4. AI Agents in Human Resources - AI agents are revolutionizing HR practices by automating and optimizing key functions: - - - **Recruiting**: AI agents can screen resumes, schedule interviews, and even conduct initial assessments, thus accelerating the hiring process while minimizing biases. - - **Succession Planning**: AI systems analyze employee performance data and potential, helping organizations identify future leaders and plan appropriate training. - - **Employee Engagement**: Chatbots powered by AI can facilitate feedback loops between employees and management, promoting an open culture and addressing concerns promptly. - - As AI continues to evolve, HR departments leveraging these agents can realize substantial improvements in both efficiency and employee satisfaction. - - ## 5. AI Agents in Finance - The finance sector is seeing extensive integration of AI agents that enhance financial practices: - - - **Expense Tracking**: Automated systems manage and monitor expenses, flagging anomalies and offering recommendations based on spending patterns. - - **Risk Assessment**: AI models assess credit risk and uncover potential fraud by analyzing transaction data and behavioral patterns. - - **Investment Decisions**: AI agents provide stock predictions and analytics based on historical data and current market conditions, empowering investors with informative insights. - - The incorporation of AI agents into finance is fostering a more responsive and risk-aware financial landscape. - - ## 6. Market Trends and Investments - The growth of AI agents has attracted significant investment, especially amidst the rising popularity of chatbots and generative AI technologies. Companies and entrepreneurs are eager to explore the potential of these systems, recognizing their ability to streamline operations and improve customer engagement. - - Conversely, corporations like Microsoft are taking strides to integrate AI agents into their product offerings, with enhancements to their Copilot 365 applications. This strategic move emphasizes the importance of AI literacy in the modern workplace and indicates the stabilizing of AI agents as essential business tools. - - ## 7. Future Predictions and Implications - Experts predict that AI agents will transform essential aspects of work life. As we look toward the future, several anticipated changes include: - - - Enhanced integration of AI agents across all business functions, creating interconnected systems that leverage data from various departmental silos for comprehensive decision-making. - - Continued advancement of AI technologies, resulting in smarter, more adaptable agents capable of learning and evolving from user interactions. - - Increased regulatory scrutiny to ensure ethical use, especially concerning data privacy and employee surveillance as AI agents become more prevalent. - - To stay competitive and harness the full potential of AI agents, organizations must remain vigilant about latest developments in AI technology and consider continuous learning and adaptation in their strategic planning. - - ## 8. Conclusion - The emergence of AI agents is undeniably reshaping the workplace landscape in 5. With their ability to automate tasks, enhance efficiency, and improve decision-making, AI agents are critical in driving operational success. Organizations must embrace and adapt to AI developments to thrive in an increasingly digital business environment. + ## 시사점 + … ``` - + + 실제 파일은 더 길고 실시간 검색 결과를 반영합니다. +## 한 번에 이해하기 + +1. **Flow** — `LatestAiFlow`는 `prepare_topic` → `run_research` → `summarize` 순으로 실행됩니다. 상태(`topic`, `report`)는 Flow에 있습니다. +2. **Crew** — `ResearchCrew`는 에이전트 한 명·작업 하나로 실행됩니다. 연구원이 **Serper**로 웹을 검색하고 구조화된 보고서를 씁니다. +3. **결과물** — 작업의 `output_file`이 `output/report.md`에 보고서를 씁니다. + +Flow 패턴(라우팅, 지속성, human-in-the-loop)을 더 보려면 [첫 Flow 만들기](/ko/guides/flows/first-flow)와 [Flows](/ko/concepts/flows)를 참고하세요. Flow 없이 crew만 쓰려면 [Crews](/ko/concepts/crews)를, 작업 없이 단일 `Agent`의 `kickoff()`만 쓰려면 [Agents](/ko/concepts/agents#direct-agent-interaction-with-kickoff)를 참고하세요. + -축하합니다! - -crew 프로젝트 설정이 완료되었으며, 이제 자신만의 agentic workflow 구축을 바로 시작하실 수 있습니다! - +에이전트 crew와 저장된 보고서까지 이어진 Flow를 완성했습니다. 이제 단계·crew·도구를 더해 확장할 수 있습니다. -### 명명 일관성에 대한 참고 +### 이름 일치 -YAML 파일(`agents.yaml` 및 `tasks.yaml`)에서 사용하는 이름은 Python 코드의 메서드 이름과 일치해야 합니다. -예를 들어, 특정 task에 대한 agent를 `tasks.yaml` 파일에서 참조할 수 있습니다. -이러한 명명 일관성을 지키면 CrewAI가 설정과 코드를 자동으로 연결할 수 있습니다. 그렇지 않으면 task가 참조를 제대로 인식하지 못할 수 있습니다. +YAML 키(`researcher`, `research_task`)는 `@CrewBase` 클래스의 메서드 이름과 같아야 합니다. 전체 데코레이터 패턴은 [Crews](/ko/concepts/crews)를 참고하세요. -#### 예시 참조 +## 배포 - - `agents.yaml` (`email_summarizer`) 파일에서 에이전트 이름과 `crew.py` - (`email_summarizer`) 파일에서 메서드 이름이 동일하게 사용되는 점에 주목하세요. - +로컬에서 정상 실행되고 프로젝트가 **GitHub** 저장소에 있으면 Flow를 **[CrewAI AMP](https://app.crewai.com)**에 올릴 수 있습니다. 프로젝트 루트에서: -```yaml agents.yaml -email_summarizer: - role: > - Email Summarizer - goal: > - Summarize emails into a concise and clear summary - backstory: > - You will create a 5 bullet point summary of the report - llm: provider/model-id # Add your choice of model here + +```bash 인증 +crewai login ``` - - `tasks.yaml` (`email_summarizer_task`) 파일에서 태스크 이름과 `crew.py` - (`email_summarizer_task`) 파일에서 메서드 이름이 동일하게 사용되는 점에 - 주목하세요. - - -```yaml tasks.yaml -email_summarizer_task: - description: > - Summarize the email into a 5 bullet point summary - expected_output: > - A 5 bullet point summary of the email - agent: email_summarizer - context: - - reporting_task - - research_task +```bash 배포 생성 +crewai deploy create ``` -## Crew 배포하기 +```bash 상태 및 로그 +crewai deploy status +crewai deploy logs +``` -production 환경에 crew를 배포하는 가장 쉬운 방법은 [CrewAI AMP](http://app.crewai.com)를 통해서입니다. +```bash 코드 변경 후 반영 +crewai deploy push +``` -CLI를 사용하여 [CrewAI AMP](http://app.crewai.com)에 crew를 배포하는 단계별 시연은 이 영상 튜토리얼을 참고하세요. +```bash 배포 목록 또는 삭제 +crewai deploy list +crewai deploy remove +``` + - + + 첫 배포는 보통 **약 1분** 정도 걸립니다. 전체 사전 요건과 웹 UI 절차는 [AMP에 배포](/ko/enterprise/guides/deploy-to-amp)를 참고하세요. + - - CrewAI AOP로 시작하여 몇 번의 클릭만으로 production 환경에 crew를 - 배포하세요. + + AMP 배포 단계별 안내(CLI 및 대시보드). - 오픈 소스 커뮤니티에 참여하여 아이디어를 나누고, 프로젝트를 공유하며, 다른 - CrewAI 개발자들과 소통하세요. + 아이디어를 나누고 프로젝트를 공유하며 다른 CrewAI 개발자와 소통하세요. diff --git a/docs/ko/skills.mdx b/docs/ko/skills.mdx new file mode 100644 index 000000000..0c789c158 --- /dev/null +++ b/docs/ko/skills.mdx @@ -0,0 +1,50 @@ +--- +title: Skills +description: skills.sh의 공식 레지스트리에서 crewaiinc/skills를 설치하세요. Claude Code, Cursor, Codex 등을 위한 Flow, Crew, 문서 연동 스킬. +icon: wand-magic-sparkles +mode: "wide" +--- + +# Skills + +**한 번의 명령으로 코딩 에이전트에 CrewAI 컨텍스트를 제공하세요.** + +CrewAI **Skills**는 **[skills.sh/crewaiinc/skills](https://skills.sh/crewaiinc/skills)**에 게시됩니다. `crewaiinc/skills`의 공식 레지스트리로, 개별 스킬(예: **design-agent**, **getting-started**, **design-task**, **ask-docs**), 설치 수, 감사 정보를 확인할 수 있습니다. Claude Code, Cursor, Codex 같은 코딩 에이전트에게 Flow 구성, Crew 설정, 도구 사용, CrewAI 패턴을 가르칩니다. 아래를 실행하거나 에이전트에 붙여 넣으세요. + +```shell Terminal +npx skills add crewaiinc/skills +``` + +에이전트 워크플로에 스킬 팩이 추가되어 세션마다 프레임워크를 다시 설명하지 않아도 CrewAI 관례를 적용할 수 있습니다. 소스와 이슈는 [GitHub](https://github.com/crewAIInc/skills)에서 관리합니다. + +## 에이전트가 얻는 것 + +- **Flows** — CrewAI 방식의 상태ful 앱, 단계, crew kickoff +- **Crew & 에이전트** — YAML 우선 패턴, 역할, 작업, 위임 +- **도구 & 통합** — 검색, API, 일반적인 CrewAI 도구 연결 +- **프로젝트 구조** — CLI 스캐폴드 및 저장소 관례와 정렬 +- **최신 패턴** — 스킬이 현재 CrewAI 문서 및 권장 사항을 반영 + +## 이 사이트에서 더 알아보기 + + + + CrewAI와 `AGENTS.md`, 코딩 에이전트 워크플로 사용법. + + + 첫 Flow와 crew를 처음부터 끝까지 구축합니다. + + + CrewAI CLI와 Python 패키지를 설치합니다. + + + `crewaiinc/skills` 공식 목록—스킬, 설치 수, 감사. + + + 스킬 팩 소스, 업데이트, 이슈. + + + +### 영상: 코딩 에이전트 스킬과 CrewAI + + + ## Tutorial em Vídeo Assista a este tutorial em vídeo para uma demonstração passo a passo do processo de instalação: @@ -192,12 +200,11 @@ Para equipes e organizações, o CrewAI oferece opções de implantação corpor - Siga nosso guia de início rápido para criar seu primeiro agente CrewAI e - obter experiência prática. + Siga o guia rápido para gerar um Flow, executar um crew com um agente e produzir um relatório. + ## A Arquitetura do CrewAI A arquitetura do CrewAI foi projetada para equilibrar autonomia com controle. @@ -132,7 +140,7 @@ Para qualquer aplicação pronta para produção, **comece com um Flow**. icon="bolt" href="/pt-BR/quickstart" > - Siga nosso guia rápido para criar seu primeiro agente CrewAI e colocar a mão na massa. + Gere um Flow, execute um crew com um agente e produza um relatório ponta a ponta. + **Quer publicar sua ferramenta para a comunidade?** Se você está construindo uma ferramenta que pode beneficiar outros, confira o guia [Publicar Ferramentas Personalizadas](/pt-BR/guides/tools/publish-custom-tools) para aprender como empacotar e distribuir sua ferramenta no PyPI. + + ### Subclassificando `BaseTool` Para criar uma ferramenta personalizada, herde de `BaseTool` e defina os atributos necessários, incluindo o `args_schema` para validação de entrada e o método `_run`. diff --git a/docs/pt-BR/learn/streaming-crew-execution.mdx b/docs/pt-BR/learn/streaming-crew-execution.mdx index 85a26e370..4a3df07ef 100644 --- a/docs/pt-BR/learn/streaming-crew-execution.mdx +++ b/docs/pt-BR/learn/streaming-crew-execution.mdx @@ -325,6 +325,34 @@ O streaming é particularmente valioso para: - **Experiência do Usuário**: Reduzir latência percebida mostrando resultados incrementais - **Dashboards ao Vivo**: Construir interfaces de monitoramento que exibem status de execução da crew +## Cancelamento e Limpeza de Recursos + +`CrewStreamingOutput` suporta cancelamento gracioso para que o trabalho em andamento pare imediatamente quando o consumidor desconecta. + +### Gerenciador de Contexto Assíncrono + +```python Code +streaming = await crew.akickoff(inputs={"topic": "AI"}) + +async with streaming: + async for chunk in streaming: + print(chunk.content, end="", flush=True) +``` + +### Cancelamento Explícito + +```python Code +streaming = await crew.akickoff(inputs={"topic": "AI"}) +try: + async for chunk in streaming: + print(chunk.content, end="", flush=True) +finally: + await streaming.aclose() # assíncrono + # streaming.close() # equivalente síncrono +``` + +Após o cancelamento, `streaming.is_cancelled` e `streaming.is_completed` são ambos `True`. Tanto `aclose()` quanto `close()` são idempotentes. + ## Notas Importantes - O streaming ativa automaticamente o streaming do LLM para todos os agentes na crew diff --git a/docs/pt-BR/quickstart.mdx b/docs/pt-BR/quickstart.mdx index 58d079bc1..4129d7995 100644 --- a/docs/pt-BR/quickstart.mdx +++ b/docs/pt-BR/quickstart.mdx @@ -1,374 +1,278 @@ --- title: Guia Rápido -description: Construa seu primeiro agente de IA com a CrewAI em menos de 5 minutos. +description: Crie seu primeiro Flow CrewAI em minutos — orquestração, estado e um crew com um agente que gera um relatório real. icon: rocket mode: "wide" --- -## Construa seu primeiro Agente CrewAI +### Assista: Construindo Agents e Flows CrewAI com Coding Agent Skills -Vamos criar uma tripulação simples que nos ajudará a `pesquisar` e `relatar` sobre os `últimos avanços em IA` para um determinado tópico ou assunto. +Instale nossas coding agent skills (Claude Code, Codex, ...) para colocar seus agentes de código para funcionar rapidamente com o CrewAI. -Antes de prosseguir, certifique-se de ter concluído a instalação da CrewAI. -Se ainda não instalou, faça isso seguindo o [guia de instalação](/pt-BR/installation). +Você pode instalar com `npx skills add crewaiinc/skills` -Siga os passos abaixo para começar a tripular! 🚣‍♂️ + + +Neste guia você vai **criar um Flow** que define um tópico de pesquisa, executa um **crew com um agente** (um pesquisador com busca na web) e termina com um **relatório em Markdown** no disco. Flows são a forma recomendada de estruturar apps em produção: eles controlam **estado** e **ordem de execução**, enquanto os **agentes** fazem o trabalho dentro da etapa do crew. + +Se ainda não instalou o CrewAI, siga primeiro o [guia de instalação](/pt-BR/installation). + +## Pré-requisitos + +- Ambiente Python e a CLI do CrewAI (veja [instalação](/pt-BR/installation)) +- Um LLM configurado com as chaves corretas — veja [LLMs](/pt-BR/concepts/llms#setting-up-your-llm) +- Uma chave de API do [Serper.dev](https://serper.dev/) (`SERPER_API_KEY`) para busca na web neste tutorial + +## Construa seu primeiro Flow - - Crie um novo projeto de tripulação executando o comando abaixo em seu terminal. - Isso criará um novo diretório chamado `latest-ai-development` com a estrutura básica para sua tripulação. + + No terminal, gere um projeto Flow (o nome da pasta usa sublinhados, ex.: `latest_ai_flow`): + ```shell Terminal - crewai create crew latest-ai-development + crewai create flow latest-ai-flow + cd latest_ai_flow ``` + + Isso cria um app Flow em `src/latest_ai_flow/`, incluindo um crew inicial em `crews/content_crew/` que você substituirá por um crew de pesquisa **com um único agente** nos próximos passos. - - - ```shell Terminal - cd latest_ai_development - ``` - - - - - Você também pode modificar os agentes conforme necessário para atender ao seu caso de uso ou copiar e colar como está para seu projeto. - Qualquer variável interpolada nos seus arquivos `agents.yaml` e `tasks.yaml`, como `{topic}`, será substituída pelo valor da variável no arquivo `main.py`. - + + + Substitua o conteúdo de `src/latest_ai_flow/crews/content_crew/config/agents.yaml` por um único pesquisador. Variáveis como `{topic}` são preenchidas a partir de `crew.kickoff(inputs=...)`. + ```yaml agents.yaml - # src/latest_ai_development/config/agents.yaml + # src/latest_ai_flow/crews/content_crew/config/agents.yaml researcher: role: > - Pesquisador Sênior de Dados em {topic} + Pesquisador(a) Sênior de Dados em {topic} goal: > - Descobrir os avanços mais recentes em {topic} + Descobrir os desenvolvimentos mais recentes em {topic} backstory: > - Você é um pesquisador experiente com talento para descobrir os últimos avanços em {topic}. Conhecido por sua habilidade em encontrar as informações mais relevantes e apresentá-las de forma clara e concisa. - - reporting_analyst: - role: > - Analista de Relatórios em {topic} - goal: > - Criar relatórios detalhados com base na análise de dados e descobertas de pesquisa em {topic} - backstory: > - Você é um analista meticuloso com um olhar atento aos detalhes. É conhecido por sua capacidade de transformar dados complexos em relatórios claros e concisos, facilitando o entendimento e a tomada de decisão por parte dos outros. + Você é um pesquisador experiente que descobre os últimos avanços em {topic}. + Encontra as informações mais relevantes e apresenta tudo com clareza. ``` - + + ```yaml tasks.yaml - # src/latest_ai_development/config/tasks.yaml + # src/latest_ai_flow/crews/content_crew/config/tasks.yaml research_task: description: > - Realize uma pesquisa aprofundada sobre {topic}. - Certifique-se de encontrar informações interessantes e relevantes considerando que o ano atual é 2025. + Faça uma pesquisa aprofundada sobre {topic}. Use busca na web para obter + informações atuais e confiáveis. O ano atual é 2026. expected_output: > - Uma lista com 10 tópicos dos dados mais relevantes sobre {topic} + Um relatório em markdown com seções claras: tendências principais, ferramentas + ou empresas relevantes e implicações. Entre 800 e 1200 palavras. Sem cercas de código em volta do documento inteiro. agent: researcher - - reporting_task: - description: > - Revise o contexto obtido e expanda cada tópico em uma seção completa para um relatório. - Certifique-se de que o relatório seja detalhado e contenha todas as informações relevantes. - expected_output: > - Um relatório completo com os principais tópicos, cada um com uma seção detalhada de informações. - Formate como markdown sem usar '```' - agent: reporting_analyst - output_file: report.md + output_file: output/report.md ``` - - ```python crew.py - # src/latest_ai_development/crew.py - from crewai import Agent, Crew, Process, Task - from crewai.project import CrewBase, agent, crew, task - from crewai_tools import SerperDevTool - from crewai.agents.agent_builder.base_agent import BaseAgent + + + Aponte o crew gerado para o YAML e anexe `SerperDevTool` ao pesquisador. + + ```python content_crew.py + # src/latest_ai_flow/crews/content_crew/content_crew.py from typing import List + from crewai import Agent, Crew, Process, Task + from crewai.agents.agent_builder.base_agent import BaseAgent + from crewai.project import CrewBase, agent, crew, task + from crewai_tools import SerperDevTool + + @CrewBase - class LatestAiDevelopmentCrew(): - """LatestAiDevelopment crew""" + class ResearchCrew: + """Crew de pesquisa com um agente, usado dentro do Flow.""" agents: List[BaseAgent] tasks: List[Task] + agents_config = "config/agents.yaml" + tasks_config = "config/tasks.yaml" + @agent def researcher(self) -> Agent: return Agent( - config=self.agents_config['researcher'], # type: ignore[index] + config=self.agents_config["researcher"], # type: ignore[index] verbose=True, - tools=[SerperDevTool()] - ) - - @agent - def reporting_analyst(self) -> Agent: - return Agent( - config=self.agents_config['reporting_analyst'], # type: ignore[index] - verbose=True + tools=[SerperDevTool()], ) @task def research_task(self) -> Task: return Task( - config=self.tasks_config['research_task'], # type: ignore[index] - ) - - @task - def reporting_task(self) -> Task: - return Task( - config=self.tasks_config['reporting_task'], # type: ignore[index] - output_file='output/report.md' # Este é o arquivo que conterá o relatório final. + config=self.tasks_config["research_task"], # type: ignore[index] ) @crew def crew(self) -> Crew: - """Creates the LatestAiDevelopment crew""" return Crew( - agents=self.agents, # Criado automaticamente pelo decorador @agent - tasks=self.tasks, # Criado automaticamente pelo decorador @task + agents=self.agents, + tasks=self.tasks, process=Process.sequential, verbose=True, ) ``` - - ```python crew.py - # src/latest_ai_development/crew.py - from crewai import Agent, Crew, Process, Task - from crewai.project import CrewBase, agent, crew, task, before_kickoff, after_kickoff - from crewai_tools import SerperDevTool - @CrewBase - class LatestAiDevelopmentCrew(): - """LatestAiDevelopment crew""" + + Conecte o crew a um Flow: um passo `@start()` define o tópico no **estado** e um `@listen` executa o crew. O `output_file` da tarefa continua gravando `output/report.md`. - @before_kickoff - def before_kickoff_function(self, inputs): - print(f"Before kickoff function with inputs: {inputs}") - return inputs # You can return the inputs or modify them as needed - - @after_kickoff - def after_kickoff_function(self, result): - print(f"After kickoff function with result: {result}") - return result # You can return the result or modify it as needed - - # ... remaining code - ``` - - - - Por exemplo, você pode passar o input `topic` para sua tripulação para personalizar a pesquisa e o relatório. ```python main.py - #!/usr/bin/env python - # src/latest_ai_development/main.py - import sys - from latest_ai_development.crew import LatestAiDevelopmentCrew + # src/latest_ai_flow/main.py + from pydantic import BaseModel - def run(): - """ - Run the crew. - """ - inputs = { - 'topic': 'AI Agents' - } - LatestAiDevelopmentCrew().crew().kickoff(inputs=inputs) + from crewai.flow import Flow, listen, start + + from latest_ai_flow.crews.content_crew.content_crew import ResearchCrew + + + class ResearchFlowState(BaseModel): + topic: str = "" + report: str = "" + + + class LatestAiFlow(Flow[ResearchFlowState]): + @start() + def prepare_topic(self, crewai_trigger_payload: dict | None = None): + if crewai_trigger_payload: + self.state.topic = crewai_trigger_payload.get("topic", "AI Agents") + else: + self.state.topic = "AI Agents" + print(f"Tópico: {self.state.topic}") + + @listen(prepare_topic) + def run_research(self): + result = ResearchCrew().crew().kickoff(inputs={"topic": self.state.topic}) + self.state.report = result.raw + print("Crew de pesquisa concluído.") + + @listen(run_research) + def summarize(self): + print("Relatório em: output/report.md") + + + def kickoff(): + LatestAiFlow().kickoff() + + + def plot(): + LatestAiFlow().plot() + + + if __name__ == "__main__": + kickoff() ``` - - - Antes de executar sua tripulação, certifique-se de ter as seguintes chaves configuradas como variáveis de ambiente no seu arquivo `.env`: - - Uma chave da API do [Serper.dev](https://serper.dev/): `SERPER_API_KEY=YOUR_KEY_HERE` - - A configuração do modelo de sua escolha, como uma chave de API. Veja o - [guia de configuração do LLM](/pt-BR/concepts/llms#setting-up-your-llm) para aprender como configurar modelos de qualquer provedor. - - - - Trave e instale as dependências utilizando o comando da CLI: - - ```shell Terminal - crewai install - ``` - - - Se quiser instalar pacotes adicionais, faça isso executando: - - ```shell Terminal - uv add - ``` - - - - - Para executar sua tripulação, rode o seguinte comando na raiz do projeto: - - ```bash Terminal - crewai run - ``` - + + Se o nome do pacote não for `latest_ai_flow`, ajuste o import de `ResearchCrew` para o caminho de módulo do seu projeto. + - - Para usuários do CrewAI AMP, você pode criar a mesma tripulação sem escrever código: + + Na raiz do projeto, no arquivo `.env`, defina: -1. Faça login na sua conta CrewAI AMP (crie uma conta gratuita em [app.crewai.com](https://app.crewai.com)) -2. Abra o Crew Studio -3. Digite qual automação deseja construir -4. Crie suas tarefas visualmente e conecte-as em sequência -5. Configure seus inputs e clique em "Download Code" ou "Deploy" - -![Crew Studio Quickstart](/images/enterprise/crew-studio-interface.png) - - - Comece sua conta gratuita no CrewAI AMP - + - `SERPER_API_KEY` — obtida em [Serper.dev](https://serper.dev/) + - As chaves do provedor de modelo conforme necessário — veja [configuração de LLM](/pt-BR/concepts/llms#setting-up-your-llm) - - Você verá a saída no console e o arquivo `report.md` deve ser criado na raiz do seu projeto com o relatório final. -Veja um exemplo de como o relatório deve ser: + + + ```shell Terminal + crewai install + crewai run + ``` + + + O `crewai run` executa o ponto de entrada do Flow definido no projeto (o mesmo comando dos crews; o tipo do projeto é `"flow"` no `pyproject.toml`). + + + + Você deve ver logs do Flow e do crew. Abra **`output/report.md`** para o relatório gerado (trecho): ```markdown output/report.md - # Relatório Abrangente sobre a Ascensão e o Impacto dos Agentes de IA em 2025 + # Agentes de IA em 2026: panorama e tendências - ## 1. Introduction to AI Agents - In 2025, Artificial Intelligence (AI) agents are at the forefront of innovation across various industries. As intelligent systems that can perform tasks typically requiring human cognition, AI agents are paving the way for significant advancements in operational efficiency, decision-making, and overall productivity within sectors like Human Resources (HR) and Finance. This report aims to detail the rise of AI agents, their frameworks, applications, and potential implications on the workforce. + ## Resumo executivo + … - ## 2. Benefits of AI Agents - AI agents bring numerous advantages that are transforming traditional work environments. Key benefits include: + ## Principais tendências + - **Uso de ferramentas e orquestração** — … + - **Adoção empresarial** — … - - **Task Automation**: AI agents can carry out repetitive tasks such as data entry, scheduling, and payroll processing without human intervention, greatly reducing the time and resources spent on these activities. - - **Improved Efficiency**: By quickly processing large datasets and performing analyses that would take humans significantly longer, AI agents enhance operational efficiency. This allows teams to focus on strategic tasks that require higher-level thinking. - - **Enhanced Decision-Making**: AI agents can analyze trends and patterns in data, provide insights, and even suggest actions, helping stakeholders make informed decisions based on factual data rather than intuition alone. - - ## 3. Popular AI Agent Frameworks - Several frameworks have emerged to facilitate the development of AI agents, each with its own unique features and capabilities. Some of the most popular frameworks include: - - - **Autogen**: A framework designed to streamline the development of AI agents through automation of code generation. - - **Semantic Kernel**: Focuses on natural language processing and understanding, enabling agents to comprehend user intentions better. - - **Promptflow**: Provides tools for developers to create conversational agents that can navigate complex interactions seamlessly. - - **Langchain**: Specializes in leveraging various APIs to ensure agents can access and utilize external data effectively. - - **CrewAI**: Aimed at collaborative environments, CrewAI strengthens teamwork by facilitating communication through AI-driven insights. - - **MemGPT**: Combines memory-optimized architectures with generative capabilities, allowing for more personalized interactions with users. - - These frameworks empower developers to build versatile and intelligent agents that can engage users, perform advanced analytics, and execute various tasks aligned with organizational goals. - - ## 4. AI Agents in Human Resources - AI agents are revolutionizing HR practices by automating and optimizing key functions: - - - **Recruiting**: AI agents can screen resumes, schedule interviews, and even conduct initial assessments, thus accelerating the hiring process while minimizing biases. - - **Succession Planning**: AI systems analyze employee performance data and potential, helping organizations identify future leaders and plan appropriate training. - - **Employee Engagement**: Chatbots powered by AI can facilitate feedback loops between employees and management, promoting an open culture and addressing concerns promptly. - - As AI continues to evolve, HR departments leveraging these agents can realize substantial improvements in both efficiency and employee satisfaction. - - ## 5. AI Agents in Finance - The finance sector is seeing extensive integration of AI agents that enhance financial practices: - - - **Expense Tracking**: Automated systems manage and monitor expenses, flagging anomalies and offering recommendations based on spending patterns. - - **Risk Assessment**: AI models assess credit risk and uncover potential fraud by analyzing transaction data and behavioral patterns. - - **Investment Decisions**: AI agents provide stock predictions and analytics based on historical data and current market conditions, empowering investors with informative insights. - - The incorporation of AI agents into finance is fostering a more responsive and risk-aware financial landscape. - - ## 6. Market Trends and Investments - The growth of AI agents has attracted significant investment, especially amidst the rising popularity of chatbots and generative AI technologies. Companies and entrepreneurs are eager to explore the potential of these systems, recognizing their ability to streamline operations and improve customer engagement. - - Conversely, corporations like Microsoft are taking strides to integrate AI agents into their product offerings, with enhancements to their Copilot 365 applications. This strategic move emphasizes the importance of AI literacy in the modern workplace and indicates the stabilizing of AI agents as essential business tools. - - ## 7. Future Predictions and Implications - Experts predict that AI agents will transform essential aspects of work life. As we look toward the future, several anticipated changes include: - - - Enhanced integration of AI agents across all business functions, creating interconnected systems that leverage data from various departmental silos for comprehensive decision-making. - - Continued advancement of AI technologies, resulting in smarter, more adaptable agents capable of learning and evolving from user interactions. - - Increased regulatory scrutiny to ensure ethical use, especially concerning data privacy and employee surveillance as AI agents become more prevalent. - - To stay competitive and harness the full potential of AI agents, organizations must remain vigilant about latest developments in AI technology and consider continuous learning and adaptation in their strategic planning. - - ## 8. Conclusion - The emergence of AI agents is undeniably reshaping the workplace landscape in 5. With their ability to automate tasks, enhance efficiency, and improve decision-making, AI agents are critical in driving operational success. Organizations must embrace and adapt to AI developments to thrive in an increasingly digital business environment. + ## Implicações + … ``` - + + O arquivo real será mais longo e refletirá resultados de busca ao vivo. +## Como isso se encaixa + +1. **Flow** — `LatestAiFlow` executa `prepare_topic`, depois `run_research`, depois `summarize`. O estado (`topic`, `report`) fica no Flow. +2. **Crew** — `ResearchCrew` executa uma tarefa com um agente: o pesquisador usa **Serper** na web e escreve o relatório. +3. **Artefato** — O `output_file` da tarefa grava o relatório em `output/report.md`. + +Para ir além em Flows (roteamento, persistência, human-in-the-loop), veja [Construa seu primeiro Flow](/pt-BR/guides/flows/first-flow) e [Flows](/pt-BR/concepts/flows). Para crews sem Flow, veja [Crews](/pt-BR/concepts/crews). Para um único `Agent` com `kickoff()` sem tarefas, veja [Agents](/pt-BR/concepts/agents#direct-agent-interaction-with-kickoff). + -Parabéns! - -Você configurou seu projeto de tripulação com sucesso e está pronto para começar a construir seus próprios fluxos de trabalho baseados em agentes! - +Você tem um Flow ponta a ponta com um crew de agente e um relatório salvo — uma base sólida para novas etapas, crews ou ferramentas. -### Observação sobre Consistência nos Nomes +### Consistência de nomes -Os nomes utilizados nos seus arquivos YAML (`agents.yaml` e `tasks.yaml`) devem corresponder aos nomes dos métodos no seu código Python. -Por exemplo, você pode referenciar o agente para tarefas específicas a partir do arquivo `tasks.yaml`. -Essa consistência de nomes permite que a CrewAI conecte automaticamente suas configurações ao seu código; caso contrário, sua tarefa não reconhecerá a referência corretamente. +As chaves do YAML (`researcher`, `research_task`) devem coincidir com os nomes dos métodos na classe `@CrewBase`. Veja [Crews](/pt-BR/concepts/crews) para o padrão completo com decoradores. -#### Exemplos de Referências +## Implantação - - Observe como usamos o mesmo nome para o agente no arquivo `agents.yaml` - (`email_summarizer`) e no método do arquivo `crew.py` (`email_summarizer`). - +Envie seu Flow para o **[CrewAI AMP](https://app.crewai.com)** quando rodar localmente e o projeto estiver em um repositório **GitHub**. Na raiz do projeto: -```yaml agents.yaml -email_summarizer: - role: > - Email Summarizer - goal: > - Summarize emails into a concise and clear summary - backstory: > - You will create a 5 bullet point summary of the report - llm: provider/model-id # Add your choice of model here + +```bash Autenticar +crewai login ``` - - Observe como usamos o mesmo nome para a tarefa no arquivo `tasks.yaml` - (`email_summarizer_task`) e no método no arquivo `crew.py` - (`email_summarizer_task`). - - -```yaml tasks.yaml -email_summarizer_task: - description: > - Summarize the email into a 5 bullet point summary - expected_output: > - A 5 bullet point summary of the email - agent: email_summarizer - context: - - reporting_task - - research_task +```bash Criar implantação +crewai deploy create ``` -## Fazendo o Deploy da Sua Tripulação +```bash Status e logs +crewai deploy status +crewai deploy logs +``` -A forma mais fácil de fazer deploy da sua tripulação em produção é através da [CrewAI AMP](http://app.crewai.com). +```bash Enviar atualizações após mudanças no código +crewai deploy push +``` -Assista a este vídeo tutorial para uma demonstração detalhada de como fazer deploy da sua tripulação na [CrewAI AMP](http://app.crewai.com) usando a CLI. +```bash Listar ou remover implantações +crewai deploy list +crewai deploy remove +``` + - + + A primeira implantação costuma levar **cerca de 1 minuto**. Pré-requisitos completos e fluxo na interface web estão em [Implantar no AMP](/pt-BR/enterprise/guides/deploy-to-amp). + - - Comece com o CrewAI AMP e faça o deploy da sua tripulação em ambiente de - produção com apenas alguns cliques. + + AMP passo a passo (CLI e painel). - Participe da nossa comunidade open source para discutir ideias, compartilhar - seus projetos e conectar-se com outros desenvolvedores CrewAI. + Troque ideias, compartilhe projetos e conecte-se com outros desenvolvedores CrewAI. diff --git a/docs/pt-BR/skills.mdx b/docs/pt-BR/skills.mdx new file mode 100644 index 000000000..acd372d3f --- /dev/null +++ b/docs/pt-BR/skills.mdx @@ -0,0 +1,50 @@ +--- +title: Skills +description: Instale crewaiinc/skills pelo registro oficial em skills.sh—Flows, Crews e agentes alinhados à documentação para Claude Code, Cursor, Codex e outros. +icon: wand-magic-sparkles +mode: "wide" +--- + +# Skills + +**Dê ao seu agente de código o contexto do CrewAI em um comando.** + +As **Skills** do CrewAI são publicadas em **[skills.sh/crewaiinc/skills](https://skills.sh/crewaiinc/skills)**—o registro oficial de `crewaiinc/skills`, com cada skill (por exemplo **design-agent**, **getting-started**, **design-task** e **ask-docs**), estatísticas de instalação e auditorias. Ensinam agentes de código—como Claude Code, Cursor e Codex—a estruturar Flows, configurar Crews, usar ferramentas e seguir os padrões do CrewAI. Execute o comando abaixo (ou cole no seu agente). + +```shell Terminal +npx skills add crewaiinc/skills +``` + +Isso adiciona o pacote de skills ao fluxo do seu agente para aplicar convenções do CrewAI sem precisar reexplicar o framework a cada sessão. Código-fonte e issues ficam no [GitHub](https://github.com/crewAIInc/skills). + +## O que seu agente ganha + +- **Flows** — apps com estado, passos e kickoffs de crew no estilo CrewAI +- **Crews e agentes** — padrões YAML-first, papéis, tarefas e delegação +- **Ferramentas e integrações** — conectar agentes a busca, APIs e ferramentas comuns +- **Layout de projeto** — alinhar com scaffolds da CLI e convenções do repositório +- **Padrões atualizados** — skills acompanham a documentação e as práticas recomendadas + +## Saiba mais neste site + + + + Como usar `AGENTS.md` e fluxos de agente de código com o CrewAI. + + + Construa seu primeiro Flow e crew ponta a ponta. + + + Instale a CLI e o pacote Python do CrewAI. + + + Listagem oficial de `crewaiinc/skills`—skills, instalações e auditorias. + + + Fonte, atualizações e issues do pacote de skills. + + + +### Vídeo: CrewAI com coding agent skills + +