From b890ac0dd0d6af84d7ec21e5b9f9fb97916be8a2 Mon Sep 17 00:00:00 2001 From: alex-clawd Date: Tue, 24 Mar 2026 23:42:39 -0700 Subject: [PATCH 01/25] fix: use __router_paths__ for listener+router methods in FlowMeta (#5064) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit When a method has both @listen and @human_feedback(emit=[...]), the FlowMeta metaclass registered it as a router but only used get_possible_return_constants() to detect paths. This fails for @human_feedback methods since the paths come from the decorator's emit param, not from return statements in the source code. Now checks __router_paths__ first (set by @human_feedback), then falls back to source code analysis for plain @router methods. This was causing missing edges in the flow serializer output — e.g. the whitepaper generator's review_infographic -> handle_cancelled, send_slack_notification, classify_feedback edges were all missing. Adds test: @listen + @human_feedback(emit=[...]) generates correct router edges in serialized output. Co-authored-by: Joao Moura --- lib/crewai/src/crewai/flow/flow.py | 16 ++++++-- lib/crewai/tests/test_flow_serializer.py | 52 ++++++++++++++++++++++++ 2 files changed, 64 insertions(+), 4 deletions(-) diff --git a/lib/crewai/src/crewai/flow/flow.py b/lib/crewai/src/crewai/flow/flow.py index 48bf887c4..1c1aa90b5 100644 --- a/lib/crewai/src/crewai/flow/flow.py +++ b/lib/crewai/src/crewai/flow/flow.py @@ -778,11 +778,19 @@ class FlowMeta(type): and attr_value.__is_router__ ): routers.add(attr_name) - possible_returns = get_possible_return_constants(attr_value) - if possible_returns: - router_paths[attr_name] = possible_returns + # First check for explicit __router_paths__ (set by @human_feedback(emit=[...])) + if ( + hasattr(attr_value, "__router_paths__") + and attr_value.__router_paths__ + ): + router_paths[attr_name] = attr_value.__router_paths__ else: - router_paths[attr_name] = [] + # Fall back to source code analysis for @router methods + possible_returns = get_possible_return_constants(attr_value) + if possible_returns: + router_paths[attr_name] = possible_returns + else: + router_paths[attr_name] = [] # Handle start methods that are also routers (e.g., @human_feedback with emit) if ( diff --git a/lib/crewai/tests/test_flow_serializer.py b/lib/crewai/tests/test_flow_serializer.py index 952325deb..53d935e95 100644 --- a/lib/crewai/tests/test_flow_serializer.py +++ b/lib/crewai/tests/test_flow_serializer.py @@ -224,6 +224,58 @@ class TestHumanFeedbackMethods: assert method_map["handle_approved"]["has_human_feedback"] is False assert method_map["handle_rejected"]["has_human_feedback"] is False + def test_listen_plus_human_feedback_router_edges(self): + """Test that @listen + @human_feedback(emit=...) generates router edges. + + This is the pattern used in the whitepaper generator: + a listener method that also acts as a router via @human_feedback(emit=[...]). + The serializer must generate edges from this method to listeners of its emit paths. + """ + + class ReviewFlow(Flow): + @start() + def generate(self): + return "content" + + @listen(generate) + @human_feedback( + message="Review this:", + emit=["approved", "needs_changes", "cancelled"], + llm="gpt-4o-mini", + ) + def review(self): + return "review result" + + @listen("approved") + def handle_approved(self): + return "done" + + @listen("needs_changes") + def handle_changes(self): + return "regenerating" + + @listen("cancelled") + def handle_cancelled(self): + return "cancelled" + + structure = flow_structure(ReviewFlow) + + method_map = {m["name"]: m for m in structure["methods"]} + edge_set = {(e["from_method"], e["to_method"], e.get("condition")) for e in structure["edges"]} + + # review should be detected as a router with the emit paths + assert method_map["review"]["type"] == "router" + assert set(method_map["review"]["router_paths"]) == {"approved", "needs_changes", "cancelled"} + assert method_map["review"]["has_human_feedback"] is True + + # Should have listen edge: generate -> review + assert ("generate", "review", None) in edge_set + + # Should have route edges from review to each listener + assert ("review", "handle_approved", "approved") in edge_set + assert ("review", "handle_changes", "needs_changes") in edge_set + assert ("review", "handle_cancelled", "cancelled") in edge_set + class TestCrewReferences: """Test detection of Crew references in method bodies.""" From f5b3b2a3556db6ace96da7fc5ce8b518c0926fb1 Mon Sep 17 00:00:00 2001 From: Greyson LaLonde Date: Wed, 25 Mar 2026 15:44:02 +0800 Subject: [PATCH 02/25] docs: add modern standard arabic translation of all documentation --- docs/ar/api-reference/inputs.mdx | 8 + docs/ar/api-reference/introduction.mdx | 135 ++ docs/ar/api-reference/kickoff.mdx | 8 + docs/ar/api-reference/resume.mdx | 6 + docs/ar/api-reference/status.mdx | 6 + docs/ar/changelog.mdx | 209 ++ docs/ar/concepts/agents.mdx | 361 ++++ docs/ar/concepts/cli.mdx | 287 +++ docs/ar/concepts/collaboration.mdx | 363 ++++ docs/ar/concepts/crews.mdx | 204 ++ docs/ar/concepts/event-listener.mdx | 236 ++ docs/ar/concepts/files.mdx | 267 +++ docs/ar/concepts/flows.mdx | 1068 ++++++++++ docs/ar/concepts/knowledge.mdx | 1095 ++++++++++ docs/ar/concepts/llms.mdx | 1464 +++++++++++++ docs/ar/concepts/memory.mdx | 878 ++++++++ docs/ar/concepts/planning.mdx | 155 ++ docs/ar/concepts/processes.mdx | 67 + docs/ar/concepts/production-architecture.mdx | 154 ++ docs/ar/concepts/reasoning.mdx | 148 ++ docs/ar/concepts/skills.mdx | 114 + docs/ar/concepts/tasks.mdx | 1085 ++++++++++ docs/ar/concepts/testing.mdx | 49 + docs/ar/concepts/tools.mdx | 286 +++ docs/ar/concepts/training.mdx | 197 ++ .../features/agent-repositories.mdx | 155 ++ docs/ar/enterprise/features/automations.mdx | 104 + docs/ar/enterprise/features/crew-studio.mdx | 88 + .../features/flow-hitl-management.mdx | 558 +++++ .../features/hallucination-guardrail.mdx | 251 +++ docs/ar/enterprise/features/marketplace.mdx | 45 + .../features/pii-trace-redactions.mdx | 342 +++ docs/ar/enterprise/features/rbac.mdx | 107 + .../features/tools-and-integrations.mdx | 261 +++ docs/ar/enterprise/features/traces.mdx | 148 ++ .../enterprise/features/webhook-streaming.mdx | 172 ++ .../enterprise/guides/automation-triggers.mdx | 321 +++ .../enterprise/guides/azure-openai-setup.mdx | 54 + docs/ar/enterprise/guides/build-crew.mdx | 48 + .../guides/capture_telemetry_logs.mdx | 39 + .../enterprise/guides/custom-mcp-server.mdx | 136 ++ docs/ar/enterprise/guides/deploy-to-amp.mdx | 445 ++++ .../enterprise/guides/enable-crew-studio.mdx | 182 ++ docs/ar/enterprise/guides/gmail-trigger.mdx | 97 + .../guides/google-calendar-trigger.mdx | 83 + .../guides/google-drive-trigger.mdx | 80 + docs/ar/enterprise/guides/hubspot-trigger.mdx | 61 + .../enterprise/guides/human-in-the-loop.mdx | 157 ++ docs/ar/enterprise/guides/kickoff-crew.mdx | 178 ++ .../guides/microsoft-teams-trigger.mdx | 70 + .../ar/enterprise/guides/onedrive-trigger.mdx | 69 + docs/ar/enterprise/guides/outlook-trigger.mdx | 69 + .../guides/prepare-for-deployment.mdx | 311 +++ .../guides/private-package-registry.mdx | 263 +++ .../guides/react-component-export.mdx | 112 + .../enterprise/guides/salesforce-trigger.mdx | 50 + docs/ar/enterprise/guides/slack-trigger.mdx | 62 + docs/ar/enterprise/guides/team-management.mdx | 91 + docs/ar/enterprise/guides/tool-repository.mdx | 154 ++ docs/ar/enterprise/guides/update-crew.mdx | 91 + .../enterprise/guides/webhook-automation.mdx | 157 ++ docs/ar/enterprise/guides/zapier-trigger.mdx | 105 + docs/ar/enterprise/integrations/asana.mdx | 271 +++ docs/ar/enterprise/integrations/box.mdx | 280 +++ docs/ar/enterprise/integrations/clickup.mdx | 301 +++ docs/ar/enterprise/integrations/github.mdx | 330 +++ docs/ar/enterprise/integrations/gmail.mdx | 302 +++ .../integrations/google_calendar.mdx | 366 ++++ .../integrations/google_contacts.mdx | 493 +++++ .../enterprise/integrations/google_docs.mdx | 550 +++++ .../enterprise/integrations/google_drive.mdx | 238 +++ .../enterprise/integrations/google_sheets.mdx | 254 +++ .../enterprise/integrations/google_slides.mdx | 382 ++++ docs/ar/enterprise/integrations/hubspot.mdx | 360 ++++ docs/ar/enterprise/integrations/jira.mdx | 248 +++ docs/ar/enterprise/integrations/linear.mdx | 261 +++ .../integrations/microsoft_excel.mdx | 269 +++ .../integrations/microsoft_onedrive.mdx | 218 ++ .../integrations/microsoft_outlook.mdx | 227 ++ .../integrations/microsoft_sharepoint.mdx | 270 +++ .../integrations/microsoft_teams.mdx | 205 ++ .../integrations/microsoft_word.mdx | 168 ++ docs/ar/enterprise/integrations/notion.mdx | 149 ++ .../ar/enterprise/integrations/salesforce.mdx | 331 +++ docs/ar/enterprise/integrations/shopify.mdx | 196 ++ docs/ar/enterprise/integrations/slack.mdx | 170 ++ docs/ar/enterprise/integrations/stripe.mdx | 202 ++ docs/ar/enterprise/integrations/zendesk.mdx | 262 +++ docs/ar/enterprise/introduction.mdx | 99 + .../resources/frequently-asked-questions.mdx | 152 ++ docs/ar/examples/cookbooks.mdx | 49 + docs/ar/examples/example.mdx | 86 + .../guides/advanced/customizing-prompts.mdx | 317 +++ docs/ar/guides/advanced/fingerprinting.mdx | 134 ++ .../agents/crafting-effective-agents.mdx | 453 ++++ docs/ar/guides/coding-tools/agents-md.mdx | 61 + .../guides/concepts/evaluating-use-cases.mdx | 485 +++++ docs/ar/guides/crews/first-crew.mdx | 321 +++ docs/ar/guides/flows/first-flow.mdx | 278 +++ docs/ar/guides/flows/mastering-flow-state.mdx | 184 ++ .../migration/migrating-from-langgraph.mdx | 103 + docs/ar/guides/tools/publish-custom-tools.mdx | 96 + docs/ar/index.mdx | 105 + docs/ar/installation.mdx | 209 ++ docs/ar/introduction.mdx | 144 ++ docs/ar/learn/a2a-agent-delegation.mdx | 87 + .../learn/before-and-after-kickoff-hooks.mdx | 47 + docs/ar/learn/bring-your-own-agent.mdx | 41 + docs/ar/learn/coding-agents.mdx | 80 + docs/ar/learn/conditional-tasks.mdx | 14 + docs/ar/learn/create-custom-tools.mdx | 77 + docs/ar/learn/custom-llm.mdx | 55 + docs/ar/learn/custom-manager-agent.mdx | 81 + docs/ar/learn/customizing-agents.mdx | 67 + docs/ar/learn/dalle-image-generation.mdx | 52 + docs/ar/learn/execution-hooks.mdx | 86 + docs/ar/learn/force-tool-output-as-result.mdx | 45 + docs/ar/learn/hierarchical-process.mdx | 76 + docs/ar/learn/human-feedback-in-flows.mdx | 98 + docs/ar/learn/human-in-the-loop.mdx | 80 + docs/ar/learn/human-input-on-execution.mdx | 99 + docs/ar/learn/kickoff-async.mdx | 306 +++ docs/ar/learn/kickoff-for-each.mdx | 54 + docs/ar/learn/litellm-removal-guide.mdx | 358 ++++ docs/ar/learn/llm-connections.mdx | 214 ++ docs/ar/learn/llm-hooks.mdx | 427 ++++ docs/ar/learn/llm-selection-guide.mdx | 823 +++++++ docs/ar/learn/multimodal-agents.mdx | 141 ++ docs/ar/learn/overview.mdx | 159 ++ .../replay-tasks-from-latest-crew-kickoff.mdx | 79 + docs/ar/learn/sequential-process.mdx | 128 ++ docs/ar/learn/streaming-crew-execution.mdx | 356 ++++ docs/ar/learn/streaming-flow-execution.mdx | 450 ++++ docs/ar/learn/tool-hooks.mdx | 480 +++++ docs/ar/learn/using-annotations.mdx | 151 ++ docs/ar/mcp/dsl-integration.mdx | 349 +++ docs/ar/mcp/multiple-servers.mdx | 65 + docs/ar/mcp/overview.mdx | 690 ++++++ docs/ar/mcp/security.mdx | 149 ++ docs/ar/mcp/sse.mdx | 151 ++ docs/ar/mcp/stdio.mdx | 134 ++ docs/ar/mcp/streamable-http.mdx | 136 ++ docs/ar/observability/arize-phoenix.mdx | 150 ++ docs/ar/observability/braintrust.mdx | 232 ++ docs/ar/observability/datadog.mdx | 109 + docs/ar/observability/galileo.mdx | 86 + docs/ar/observability/langdb.mdx | 167 ++ docs/ar/observability/langfuse.mdx | 109 + docs/ar/observability/langtrace.mdx | 73 + docs/ar/observability/maxim.mdx | 221 ++ docs/ar/observability/mlflow.mdx | 206 ++ docs/ar/observability/neatlogs.mdx | 134 ++ docs/ar/observability/openlit.mdx | 181 ++ docs/ar/observability/opik.mdx | 130 ++ docs/ar/observability/overview.mdx | 120 ++ docs/ar/observability/patronus-evaluation.mdx | 206 ++ docs/ar/observability/portkey.mdx | 823 +++++++ docs/ar/observability/tracing.mdx | 214 ++ docs/ar/observability/truefoundry.mdx | 146 ++ docs/ar/observability/weave.mdx | 125 ++ docs/ar/quickstart.mdx | 380 ++++ docs/ar/snippets/snippet-intro.mdx | 1 + docs/ar/telemetry.mdx | 68 + docs/ar/tools/ai-ml/aimindtool.mdx | 119 ++ docs/ar/tools/ai-ml/codeinterpretertool.mdx | 210 ++ docs/ar/tools/ai-ml/dalletool.mdx | 52 + docs/ar/tools/ai-ml/langchaintool.mdx | 59 + docs/ar/tools/ai-ml/llamaindextool.mdx | 147 ++ docs/ar/tools/ai-ml/overview.mdx | 65 + docs/ar/tools/ai-ml/ragtool.mdx | 654 ++++++ docs/ar/tools/ai-ml/visiontool.mdx | 50 + docs/ar/tools/automation/apifyactorstool.mdx | 99 + docs/ar/tools/automation/composiotool.mdx | 88 + docs/ar/tools/automation/multiontool.mdx | 127 ++ docs/ar/tools/automation/overview.mdx | 60 + .../ar/tools/automation/zapieractionstool.mdx | 59 + .../cloud-storage/bedrockkbretriever.mdx | 166 ++ docs/ar/tools/cloud-storage/overview.mdx | 51 + docs/ar/tools/cloud-storage/s3readertool.mdx | 145 ++ docs/ar/tools/cloud-storage/s3writertool.mdx | 151 ++ .../database-data/mongodbvectorsearchtool.mdx | 167 ++ docs/ar/tools/database-data/mysqltool.mdx | 67 + docs/ar/tools/database-data/nl2sqltool.mdx | 102 + docs/ar/tools/database-data/overview.mdx | 67 + docs/ar/tools/database-data/pgsearchtool.mdx | 80 + .../database-data/qdrantvectorsearchtool.mdx | 344 +++ .../database-data/singlestoresearchtool.mdx | 60 + .../database-data/snowflakesearchtool.mdx | 203 ++ .../weaviatevectorsearchtool.mdx | 168 ++ docs/ar/tools/file-document/csvsearchtool.mdx | 76 + .../tools/file-document/directoryreadtool.mdx | 52 + .../file-document/directorysearchtool.mdx | 70 + .../ar/tools/file-document/docxsearchtool.mdx | 77 + docs/ar/tools/file-document/filereadtool.mdx | 42 + docs/ar/tools/file-document/filewritetool.mdx | 47 + .../ar/tools/file-document/jsonsearchtool.mdx | 75 + docs/ar/tools/file-document/mdxsearchtool.mdx | 72 + docs/ar/tools/file-document/ocrtool.mdx | 88 + docs/ar/tools/file-document/overview.mdx | 97 + .../file-document/pdf-text-writing-tool.mdx | 75 + docs/ar/tools/file-document/pdfsearchtool.mdx | 107 + docs/ar/tools/file-document/txtsearchtool.mdx | 89 + docs/ar/tools/file-document/xmlsearchtool.mdx | 74 + .../integration/bedrockinvokeagenttool.mdx | 188 ++ .../integration/crewaiautomationtool.mdx | 276 +++ .../integration/mergeagenthandlertool.mdx | 367 ++++ docs/ar/tools/integration/overview.mdx | 76 + docs/ar/tools/overview.mdx | 140 ++ .../tools/search-research/arxivpapertool.mdx | 111 + .../tools/search-research/bravesearchtool.mdx | 314 +++ .../search-research/codedocssearchtool.mdx | 85 + .../search-research/databricks-query-tool.mdx | 81 + .../tools/search-research/exasearchtool.mdx | 110 + .../search-research/githubsearchtool.mdx | 86 + .../search-research/linkupsearchtool.mdx | 113 + docs/ar/tools/search-research/overview.mdx | 94 + .../serpapi-googlesearchtool.mdx | 66 + .../serpapi-googleshoppingtool.mdx | 62 + .../tools/search-research/serperdevtool.mdx | 107 + .../search-research/tavilyextractortool.mdx | 140 ++ .../search-research/tavilysearchtool.mdx | 125 ++ .../search-research/websitesearchtool.mdx | 78 + .../youtubechannelsearchtool.mdx | 195 ++ .../youtubevideosearchtool.mdx | 188 ++ docs/ar/tools/tool-integrations/overview.mdx | 31 + .../tools/web-scraping/brightdata-tools.mdx | 112 + .../web-scraping/browserbaseloadtool.mdx | 51 + .../firecrawlcrawlwebsitetool.mdx | 48 + .../firecrawlscrapewebsitetool.mdx | 44 + .../web-scraping/firecrawlsearchtool.mdx | 42 + .../web-scraping/hyperbrowserloadtool.mdx | 87 + docs/ar/tools/web-scraping/overview.mdx | 112 + .../web-scraping/oxylabsscraperstool.mdx | 237 +++ .../scrapeelementfromwebsitetool.mdx | 140 ++ .../web-scraping/scrapegraphscrapetool.mdx | 197 ++ .../tools/web-scraping/scrapewebsitetool.mdx | 48 + .../tools/web-scraping/scrapflyscrapetool.mdx | 221 ++ .../web-scraping/seleniumscrapingtool.mdx | 196 ++ .../web-scraping/serperscrapewebsitetool.mdx | 101 + docs/ar/tools/web-scraping/spidertool.mdx | 93 + docs/ar/tools/web-scraping/stagehandtool.mdx | 245 +++ docs/docs.json | 1892 +++++++++++++++++ 242 files changed, 47411 insertions(+) create mode 100644 docs/ar/api-reference/inputs.mdx create mode 100644 docs/ar/api-reference/introduction.mdx create mode 100644 docs/ar/api-reference/kickoff.mdx create mode 100644 docs/ar/api-reference/resume.mdx create mode 100644 docs/ar/api-reference/status.mdx create mode 100644 docs/ar/changelog.mdx create mode 100644 docs/ar/concepts/agents.mdx create mode 100644 docs/ar/concepts/cli.mdx create mode 100644 docs/ar/concepts/collaboration.mdx create mode 100644 docs/ar/concepts/crews.mdx create mode 100644 docs/ar/concepts/event-listener.mdx create mode 100644 docs/ar/concepts/files.mdx create mode 100644 docs/ar/concepts/flows.mdx create mode 100644 docs/ar/concepts/knowledge.mdx create mode 100644 docs/ar/concepts/llms.mdx create mode 100644 docs/ar/concepts/memory.mdx create mode 100644 docs/ar/concepts/planning.mdx create mode 100644 docs/ar/concepts/processes.mdx create mode 100644 docs/ar/concepts/production-architecture.mdx create mode 100644 docs/ar/concepts/reasoning.mdx create mode 100644 docs/ar/concepts/skills.mdx create mode 100644 docs/ar/concepts/tasks.mdx create mode 100644 docs/ar/concepts/testing.mdx create mode 100644 docs/ar/concepts/tools.mdx create mode 100644 docs/ar/concepts/training.mdx create mode 100644 docs/ar/enterprise/features/agent-repositories.mdx create mode 100644 docs/ar/enterprise/features/automations.mdx create mode 100644 docs/ar/enterprise/features/crew-studio.mdx create mode 100644 docs/ar/enterprise/features/flow-hitl-management.mdx create mode 100644 docs/ar/enterprise/features/hallucination-guardrail.mdx create mode 100644 docs/ar/enterprise/features/marketplace.mdx create mode 100644 docs/ar/enterprise/features/pii-trace-redactions.mdx create mode 100644 docs/ar/enterprise/features/rbac.mdx create mode 100644 docs/ar/enterprise/features/tools-and-integrations.mdx create mode 100644 docs/ar/enterprise/features/traces.mdx create mode 100644 docs/ar/enterprise/features/webhook-streaming.mdx create mode 100644 docs/ar/enterprise/guides/automation-triggers.mdx create mode 100644 docs/ar/enterprise/guides/azure-openai-setup.mdx create mode 100644 docs/ar/enterprise/guides/build-crew.mdx create mode 100644 docs/ar/enterprise/guides/capture_telemetry_logs.mdx create mode 100644 docs/ar/enterprise/guides/custom-mcp-server.mdx create mode 100644 docs/ar/enterprise/guides/deploy-to-amp.mdx create mode 100644 docs/ar/enterprise/guides/enable-crew-studio.mdx create mode 100644 docs/ar/enterprise/guides/gmail-trigger.mdx create mode 100644 docs/ar/enterprise/guides/google-calendar-trigger.mdx create mode 100644 docs/ar/enterprise/guides/google-drive-trigger.mdx create mode 100644 docs/ar/enterprise/guides/hubspot-trigger.mdx create mode 100644 docs/ar/enterprise/guides/human-in-the-loop.mdx create mode 100644 docs/ar/enterprise/guides/kickoff-crew.mdx create mode 100644 docs/ar/enterprise/guides/microsoft-teams-trigger.mdx create mode 100644 docs/ar/enterprise/guides/onedrive-trigger.mdx create mode 100644 docs/ar/enterprise/guides/outlook-trigger.mdx create mode 100644 docs/ar/enterprise/guides/prepare-for-deployment.mdx create mode 100644 docs/ar/enterprise/guides/private-package-registry.mdx create mode 100644 docs/ar/enterprise/guides/react-component-export.mdx create mode 100644 docs/ar/enterprise/guides/salesforce-trigger.mdx create mode 100644 docs/ar/enterprise/guides/slack-trigger.mdx create mode 100644 docs/ar/enterprise/guides/team-management.mdx create mode 100644 docs/ar/enterprise/guides/tool-repository.mdx create mode 100644 docs/ar/enterprise/guides/update-crew.mdx create mode 100644 docs/ar/enterprise/guides/webhook-automation.mdx create mode 100644 docs/ar/enterprise/guides/zapier-trigger.mdx create mode 100644 docs/ar/enterprise/integrations/asana.mdx create mode 100644 docs/ar/enterprise/integrations/box.mdx create mode 100644 docs/ar/enterprise/integrations/clickup.mdx create mode 100644 docs/ar/enterprise/integrations/github.mdx create mode 100644 docs/ar/enterprise/integrations/gmail.mdx create mode 100644 docs/ar/enterprise/integrations/google_calendar.mdx create mode 100644 docs/ar/enterprise/integrations/google_contacts.mdx create mode 100644 docs/ar/enterprise/integrations/google_docs.mdx create mode 100644 docs/ar/enterprise/integrations/google_drive.mdx create mode 100644 docs/ar/enterprise/integrations/google_sheets.mdx create mode 100644 docs/ar/enterprise/integrations/google_slides.mdx create mode 100644 docs/ar/enterprise/integrations/hubspot.mdx create mode 100644 docs/ar/enterprise/integrations/jira.mdx create mode 100644 docs/ar/enterprise/integrations/linear.mdx create mode 100644 docs/ar/enterprise/integrations/microsoft_excel.mdx create mode 100644 docs/ar/enterprise/integrations/microsoft_onedrive.mdx create mode 100644 docs/ar/enterprise/integrations/microsoft_outlook.mdx create mode 100644 docs/ar/enterprise/integrations/microsoft_sharepoint.mdx create mode 100644 docs/ar/enterprise/integrations/microsoft_teams.mdx create mode 100644 docs/ar/enterprise/integrations/microsoft_word.mdx create mode 100644 docs/ar/enterprise/integrations/notion.mdx create mode 100644 docs/ar/enterprise/integrations/salesforce.mdx create mode 100644 docs/ar/enterprise/integrations/shopify.mdx create mode 100644 docs/ar/enterprise/integrations/slack.mdx create mode 100644 docs/ar/enterprise/integrations/stripe.mdx create mode 100644 docs/ar/enterprise/integrations/zendesk.mdx create mode 100644 docs/ar/enterprise/introduction.mdx create mode 100644 docs/ar/enterprise/resources/frequently-asked-questions.mdx create mode 100644 docs/ar/examples/cookbooks.mdx create mode 100644 docs/ar/examples/example.mdx create mode 100644 docs/ar/guides/advanced/customizing-prompts.mdx create mode 100644 docs/ar/guides/advanced/fingerprinting.mdx create mode 100644 docs/ar/guides/agents/crafting-effective-agents.mdx create mode 100644 docs/ar/guides/coding-tools/agents-md.mdx create mode 100644 docs/ar/guides/concepts/evaluating-use-cases.mdx create mode 100644 docs/ar/guides/crews/first-crew.mdx create mode 100644 docs/ar/guides/flows/first-flow.mdx create mode 100644 docs/ar/guides/flows/mastering-flow-state.mdx create mode 100644 docs/ar/guides/migration/migrating-from-langgraph.mdx create mode 100644 docs/ar/guides/tools/publish-custom-tools.mdx create mode 100644 docs/ar/index.mdx create mode 100644 docs/ar/installation.mdx create mode 100644 docs/ar/introduction.mdx create mode 100644 docs/ar/learn/a2a-agent-delegation.mdx create mode 100644 docs/ar/learn/before-and-after-kickoff-hooks.mdx create mode 100644 docs/ar/learn/bring-your-own-agent.mdx create mode 100644 docs/ar/learn/coding-agents.mdx create mode 100644 docs/ar/learn/conditional-tasks.mdx create mode 100644 docs/ar/learn/create-custom-tools.mdx create mode 100644 docs/ar/learn/custom-llm.mdx create mode 100644 docs/ar/learn/custom-manager-agent.mdx create mode 100644 docs/ar/learn/customizing-agents.mdx create mode 100644 docs/ar/learn/dalle-image-generation.mdx create mode 100644 docs/ar/learn/execution-hooks.mdx create mode 100644 docs/ar/learn/force-tool-output-as-result.mdx create mode 100644 docs/ar/learn/hierarchical-process.mdx create mode 100644 docs/ar/learn/human-feedback-in-flows.mdx create mode 100644 docs/ar/learn/human-in-the-loop.mdx create mode 100644 docs/ar/learn/human-input-on-execution.mdx create mode 100644 docs/ar/learn/kickoff-async.mdx create mode 100644 docs/ar/learn/kickoff-for-each.mdx create mode 100644 docs/ar/learn/litellm-removal-guide.mdx create mode 100644 docs/ar/learn/llm-connections.mdx create mode 100644 docs/ar/learn/llm-hooks.mdx create mode 100644 docs/ar/learn/llm-selection-guide.mdx create mode 100644 docs/ar/learn/multimodal-agents.mdx create mode 100644 docs/ar/learn/overview.mdx create mode 100644 docs/ar/learn/replay-tasks-from-latest-crew-kickoff.mdx create mode 100644 docs/ar/learn/sequential-process.mdx create mode 100644 docs/ar/learn/streaming-crew-execution.mdx create mode 100644 docs/ar/learn/streaming-flow-execution.mdx create mode 100644 docs/ar/learn/tool-hooks.mdx create mode 100644 docs/ar/learn/using-annotations.mdx create mode 100644 docs/ar/mcp/dsl-integration.mdx create mode 100644 docs/ar/mcp/multiple-servers.mdx create mode 100644 docs/ar/mcp/overview.mdx create mode 100644 docs/ar/mcp/security.mdx create mode 100644 docs/ar/mcp/sse.mdx create mode 100644 docs/ar/mcp/stdio.mdx create mode 100644 docs/ar/mcp/streamable-http.mdx create mode 100644 docs/ar/observability/arize-phoenix.mdx create mode 100644 docs/ar/observability/braintrust.mdx create mode 100644 docs/ar/observability/datadog.mdx create mode 100644 docs/ar/observability/galileo.mdx create mode 100644 docs/ar/observability/langdb.mdx create mode 100644 docs/ar/observability/langfuse.mdx create mode 100644 docs/ar/observability/langtrace.mdx create mode 100644 docs/ar/observability/maxim.mdx create mode 100644 docs/ar/observability/mlflow.mdx create mode 100644 docs/ar/observability/neatlogs.mdx create mode 100644 docs/ar/observability/openlit.mdx create mode 100644 docs/ar/observability/opik.mdx create mode 100644 docs/ar/observability/overview.mdx create mode 100644 docs/ar/observability/patronus-evaluation.mdx create mode 100644 docs/ar/observability/portkey.mdx create mode 100644 docs/ar/observability/tracing.mdx create mode 100644 docs/ar/observability/truefoundry.mdx create mode 100644 docs/ar/observability/weave.mdx create mode 100644 docs/ar/quickstart.mdx create mode 100644 docs/ar/snippets/snippet-intro.mdx create mode 100644 docs/ar/telemetry.mdx create mode 100644 docs/ar/tools/ai-ml/aimindtool.mdx create mode 100644 docs/ar/tools/ai-ml/codeinterpretertool.mdx create mode 100644 docs/ar/tools/ai-ml/dalletool.mdx create mode 100644 docs/ar/tools/ai-ml/langchaintool.mdx create mode 100644 docs/ar/tools/ai-ml/llamaindextool.mdx create mode 100644 docs/ar/tools/ai-ml/overview.mdx create mode 100644 docs/ar/tools/ai-ml/ragtool.mdx create mode 100644 docs/ar/tools/ai-ml/visiontool.mdx create mode 100644 docs/ar/tools/automation/apifyactorstool.mdx create mode 100644 docs/ar/tools/automation/composiotool.mdx create mode 100644 docs/ar/tools/automation/multiontool.mdx create mode 100644 docs/ar/tools/automation/overview.mdx create mode 100644 docs/ar/tools/automation/zapieractionstool.mdx create mode 100644 docs/ar/tools/cloud-storage/bedrockkbretriever.mdx create mode 100644 docs/ar/tools/cloud-storage/overview.mdx create mode 100644 docs/ar/tools/cloud-storage/s3readertool.mdx create mode 100644 docs/ar/tools/cloud-storage/s3writertool.mdx create mode 100644 docs/ar/tools/database-data/mongodbvectorsearchtool.mdx create mode 100644 docs/ar/tools/database-data/mysqltool.mdx create mode 100644 docs/ar/tools/database-data/nl2sqltool.mdx create mode 100644 docs/ar/tools/database-data/overview.mdx create mode 100644 docs/ar/tools/database-data/pgsearchtool.mdx create mode 100644 docs/ar/tools/database-data/qdrantvectorsearchtool.mdx create mode 100644 docs/ar/tools/database-data/singlestoresearchtool.mdx create mode 100644 docs/ar/tools/database-data/snowflakesearchtool.mdx create mode 100644 docs/ar/tools/database-data/weaviatevectorsearchtool.mdx create mode 100644 docs/ar/tools/file-document/csvsearchtool.mdx create mode 100644 docs/ar/tools/file-document/directoryreadtool.mdx create mode 100644 docs/ar/tools/file-document/directorysearchtool.mdx create mode 100644 docs/ar/tools/file-document/docxsearchtool.mdx create mode 100644 docs/ar/tools/file-document/filereadtool.mdx create mode 100644 docs/ar/tools/file-document/filewritetool.mdx create mode 100644 docs/ar/tools/file-document/jsonsearchtool.mdx create mode 100644 docs/ar/tools/file-document/mdxsearchtool.mdx create mode 100644 docs/ar/tools/file-document/ocrtool.mdx create mode 100644 docs/ar/tools/file-document/overview.mdx create mode 100644 docs/ar/tools/file-document/pdf-text-writing-tool.mdx create mode 100644 docs/ar/tools/file-document/pdfsearchtool.mdx create mode 100644 docs/ar/tools/file-document/txtsearchtool.mdx create mode 100644 docs/ar/tools/file-document/xmlsearchtool.mdx create mode 100644 docs/ar/tools/integration/bedrockinvokeagenttool.mdx create mode 100644 docs/ar/tools/integration/crewaiautomationtool.mdx create mode 100644 docs/ar/tools/integration/mergeagenthandlertool.mdx create mode 100644 docs/ar/tools/integration/overview.mdx create mode 100644 docs/ar/tools/overview.mdx create mode 100644 docs/ar/tools/search-research/arxivpapertool.mdx create mode 100644 docs/ar/tools/search-research/bravesearchtool.mdx create mode 100644 docs/ar/tools/search-research/codedocssearchtool.mdx create mode 100644 docs/ar/tools/search-research/databricks-query-tool.mdx create mode 100644 docs/ar/tools/search-research/exasearchtool.mdx create mode 100644 docs/ar/tools/search-research/githubsearchtool.mdx create mode 100644 docs/ar/tools/search-research/linkupsearchtool.mdx create mode 100644 docs/ar/tools/search-research/overview.mdx create mode 100644 docs/ar/tools/search-research/serpapi-googlesearchtool.mdx create mode 100644 docs/ar/tools/search-research/serpapi-googleshoppingtool.mdx create mode 100644 docs/ar/tools/search-research/serperdevtool.mdx create mode 100644 docs/ar/tools/search-research/tavilyextractortool.mdx create mode 100644 docs/ar/tools/search-research/tavilysearchtool.mdx create mode 100644 docs/ar/tools/search-research/websitesearchtool.mdx create mode 100644 docs/ar/tools/search-research/youtubechannelsearchtool.mdx create mode 100644 docs/ar/tools/search-research/youtubevideosearchtool.mdx create mode 100644 docs/ar/tools/tool-integrations/overview.mdx create mode 100644 docs/ar/tools/web-scraping/brightdata-tools.mdx create mode 100644 docs/ar/tools/web-scraping/browserbaseloadtool.mdx create mode 100644 docs/ar/tools/web-scraping/firecrawlcrawlwebsitetool.mdx create mode 100644 docs/ar/tools/web-scraping/firecrawlscrapewebsitetool.mdx create mode 100644 docs/ar/tools/web-scraping/firecrawlsearchtool.mdx create mode 100644 docs/ar/tools/web-scraping/hyperbrowserloadtool.mdx create mode 100644 docs/ar/tools/web-scraping/overview.mdx create mode 100644 docs/ar/tools/web-scraping/oxylabsscraperstool.mdx create mode 100644 docs/ar/tools/web-scraping/scrapeelementfromwebsitetool.mdx create mode 100644 docs/ar/tools/web-scraping/scrapegraphscrapetool.mdx create mode 100644 docs/ar/tools/web-scraping/scrapewebsitetool.mdx create mode 100644 docs/ar/tools/web-scraping/scrapflyscrapetool.mdx create mode 100644 docs/ar/tools/web-scraping/seleniumscrapingtool.mdx create mode 100644 docs/ar/tools/web-scraping/serperscrapewebsitetool.mdx create mode 100644 docs/ar/tools/web-scraping/spidertool.mdx create mode 100644 docs/ar/tools/web-scraping/stagehandtool.mdx 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..ad6311f77 --- /dev/null +++ b/docs/ar/changelog.mdx @@ -0,0 +1,209 @@ +--- +title: "سجل التغييرات" +description: "تحديثات المنتج والتحسينات وإصلاحات الأخطاء لـ CrewAI" +icon: "clock" +mode: "wide" +--- + + ## 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/agents.mdx b/docs/ar/concepts/agents.mdx new file mode 100644 index 000000000..fe11b2545 --- /dev/null +++ b/docs/ar/concepts/agents.mdx @@ -0,0 +1,361 @@ +--- +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`: يجب أن يكون True لتشغيل الكود +- `code_execution_mode`: + - `"safe"`: يستخدم Docker (موصى به للإنتاج) + - `"unsafe"`: تنفيذ مباشر (استخدم فقط في بيئات موثوقة) + + + يشغّل هذا صورة Docker افتراضية. إذا أردت تهيئة صورة Docker، + راجع أداة Code Interpreter في قسم الأدوات. أضف أداة + مفسر الكود كأداة في معامل أداة الوكيل. + + +#### الميزات المتقدمة + +- `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: "safe"` (Docker) في بيئات الإنتاج +- فكّر في تعيين حدود `max_execution_time` مناسبة لمنع الحلقات اللانهائية + +### تحسين الأداء + +- استخدم `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/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..ea883edd1 --- /dev/null +++ b/docs/ar/concepts/skills.mdx @@ -0,0 +1,114 @@ +--- +title: المهارات +description: حزم المهارات المبنية على نظام الملفات التي تحقن السياق في إرشادات الوكيل. +icon: bolt +mode: "wide" +--- + +## نظرة عامة + +المهارات هي مجلدات مستقلة توفر للوكلاء تعليمات ومراجع وموارد خاصة بالمجال. تُعرّف كل مهارة بملف `SKILL.md` يحتوي على بيانات وصفية YAML ومحتوى Markdown. + +تستخدم المهارات **الكشف التدريجي** — يتم تحميل البيانات الوصفية أولاً، ثم التعليمات الكاملة فقط عند التفعيل، وكتالوجات الموارد فقط عند الحاجة. + +## هيكل المجلد + +``` +my-skill/ +├── SKILL.md # مطلوب — البيانات الوصفية + التعليمات +├── scripts/ # اختياري — سكربتات قابلة للتنفيذ +├── references/ # اختياري — مستندات مرجعية +└── assets/ # اختياري — ملفات ثابتة (إعدادات، بيانات) +``` + +يجب أن يتطابق اسم المجلد مع حقل `name` في `SKILL.md`. + +## تنسيق SKILL.md + +```markdown +--- +name: my-skill +description: Short description of what this skill does and when to use it. +license: Apache-2.0 # optional +compatibility: crewai>=0.1.0 # optional +metadata: # optional + author: your-name + version: "1.0" +allowed-tools: web-search file-read # optional, space-delimited +--- + +Instructions for the agent go here. This markdown body is injected +into the agent's prompt when the skill is activated. +``` + +### حقول البيانات الوصفية + +| الحقل | مطلوب | القيود | +| :-------------- | :------- | :----------------------------------------------------------------------- | +| `name` | نعم | 1-64 حرف. أحرف صغيرة أبجدية رقمية وشرطات. بدون شرطات بادئة/لاحقة/متتالية. يجب أن يطابق اسم المجلد. | +| `description` | نعم | 1-1024 حرف. يصف ما تفعله المهارة ومتى تُستخدم. | +| `license` | لا | اسم الترخيص أو مرجع لملف ترخيص مضمّن. | +| `compatibility` | لا | حد أقصى 500 حرف. متطلبات البيئة (منتجات، حزم، شبكة). | +| `metadata` | لا | تعيين مفتاح-قيمة نصي عشوائي. | +| `allowed-tools` | لا | قائمة أدوات معتمدة مسبقًا مفصولة بمسافات. تجريبي. | + +## الاستخدام + +### المهارات على مستوى الوكيل + +مرر مسارات مجلدات المهارات إلى وكيل: + +```python +from crewai import Agent + +agent = Agent( + role="Researcher", + goal="Find relevant information", + backstory="An expert researcher.", + skills=["./skills"], # يكتشف جميع المهارات في هذا المجلد +) +``` + +### المهارات على مستوى الطاقم + +تُدمج مسارات المهارات في الطاقم مع كل وكيل: + +```python +from crewai import Crew + +crew = Crew( + agents=[agent], + tasks=[task], + skills=["./skills"], +) +``` + +### المهارات المحمّلة مسبقًا + +يمكنك أيضًا تمرير كائنات `Skill` مباشرة: + +```python +from pathlib import Path +from crewai.skills import discover_skills, activate_skill + +skills = discover_skills(Path("./skills")) +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()` | + +أثناء التنفيذ العادي للوكيل، يتم اكتشاف المهارات وتفعيلها تلقائيًا. مجلدات `scripts/` و `references/` و `assets/` متاحة في مسار المهارة `path` للوكلاء الذين يحتاجون للإشارة إلى الملفات مباشرة. 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..4a0226145 --- /dev/null +++ b/docs/ar/concepts/tools.mdx @@ -0,0 +1,286 @@ +--- +title: الأدوات +description: فهم واستخدام الأدوات ضمن إطار عمل CrewAI لتعاون الوكلاء وتنفيذ المهام. +icon: screwdriver-wrench +mode: "wide" +--- + +## نظرة عامة + +تُمكّن أدوات CrewAI الوكلاء بقدرات تتراوح من البحث على الويب وتحليل البيانات إلى التعاون وتفويض المهام بين الزملاء. +توضح هذه الوثائق كيفية إنشاء هذه الأدوات ودمجها والاستفادة منها ضمن إطار عمل CrewAI، بما في ذلك التركيز على أدوات التعاون. + +## ما هي الأداة؟ + +الأداة في 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..b7ee2d9eb --- /dev/null +++ b/docs/ar/enterprise/features/rbac.mdx @@ -0,0 +1,107 @@ +--- +title: "التحكم في الوصول القائم على الأدوار (RBAC)" +description: "تحكم في الوصول إلى الطواقم والأدوات والبيانات باستخدام الأدوار والنطاقات والصلاحيات الدقيقة." +icon: "shield" +mode: "wide" +--- + +## نظرة عامة + +يتيح RBAC في CrewAI AMP إدارة وصول آمنة وقابلة للتوسع من خلال مزيج من الأدوار على مستوى المؤسسة وعناصر التحكم في الرؤية على مستوى الأتمتة. + + + نظرة عامة على RBAC في CrewAI AMP + + + +## المستخدمون والأدوار + +يُعيَّن لكل عضو في مساحة عمل CrewAI دور يحدد صلاحيات الوصول عبر الميزات المختلفة. + +يمكنك: + +- استخدام الأدوار المحددة مسبقاً (Owner، Member) +- إنشاء أدوار مخصصة مصممة لصلاحيات محددة +- تعيين الأدوار في أي وقت عبر لوحة الإعدادات + +يمكنك تهيئة المستخدمين والأدوار في Settings → Roles. + + + + انتقل إلى Settings → Roles في CrewAI AMP. + + + استخدم دوراً محدداً مسبقاً (Owner، Member) أو انقر على{" "} + Create role لتحديد دور مخصص. + + + اختر المستخدمين وعيّن لهم الدور. يمكنك تغيير ذلك في أي وقت. + + + +### ملخص التهيئة + +| المجال | مكان التهيئة | الخيارات | +| :-------------------- | :--------------------------------- | :-------------------------------------- | +| المستخدمون والأدوار | Settings → Roles | محددة مسبقاً: Owner، Member؛ أدوار مخصصة | +| رؤية الأتمتة | Automation → Settings → Visibility | خاص؛ قائمة بيضاء للمستخدمين/الأدوار | + +## التحكم في الوصول على مستوى الأتمتة + +بالإضافة إلى الأدوار على مستوى المؤسسة، تدعم أتمتات CrewAI إعدادات رؤية دقيقة تتيح لك تقييد الوصول إلى أتمتات محددة حسب المستخدم أو الدور. + +هذا مفيد لـ: + +- الحفاظ على خصوصية الأتمتات الحساسة أو التجريبية +- إدارة الرؤية عبر الفرق الكبيرة أو المتعاونين الخارجيين +- اختبار الأتمتات في سياقات معزولة + +يمكن تهيئة عمليات النشر كخاصة، مما يعني أن المستخدمين والأدوار المدرجين في القائمة البيضاء فقط سيتمكنون من: + +- عرض عملية النشر +- تشغيلها أو التفاعل مع API الخاص بها +- الوصول إلى سجلاتها ومقاييسها وإعداداتها + +يتمتع مالك المؤسسة دائماً بالوصول، بغض النظر عن إعدادات الرؤية. + +يمكنك تهيئة التحكم في الوصول على مستوى الأتمتة في Automation → Settings → علامة تبويب Visibility. + + + + انتقل إلى Automation → Settings → Visibility. + + + اختر Private لتقييد الوصول. يحتفظ مالك المؤسسة دائماً + بالوصول. + + + أضف مستخدمين وأدواراً محددة مسموح لهم بالعرض والتشغيل والوصول + إلى السجلات/المقاييس/الإعدادات. + + + احفظ التغييرات، ثم تأكد من أن المستخدمين غير المدرجين في القائمة البيضاء لا يمكنهم عرض أو تشغيل + الأتمتة. + + + +### الرؤية الخاصة: نتائج الوصول + +| الإجراء | المالك | مستخدم/دور في القائمة البيضاء | غير مدرج في القائمة البيضاء | +| :--------------------------- | :---- | :---------------------------- | :-------------------------- | +| عرض الأتمتة | ✓ | ✓ | ✗ | +| تشغيل الأتمتة/API | ✓ | ✓ | ✗ | +| الوصول إلى السجلات/المقاييس/الإعدادات | ✓ | ✓ | ✗ | + + + يتمتع مالك المؤسسة دائماً بالوصول. في الوضع الخاص، يمكن فقط للمستخدمين + والأدوار المدرجين في القائمة البيضاء العرض والتشغيل والوصول إلى السجلات/المقاييس/الإعدادات. + + + + إعدادات رؤية الأتمتة في CrewAI AMP + + + + + تواصل مع فريق الدعم للمساعدة في أسئلة 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..a7d7a137b --- /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 + ``` + + + يستغرق النشر الأول عادة 10-15 دقيقة لبناء صور الحاويات. عمليات النشر اللاحقة أسرع بكثير. + + + + + +## أوامر 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. يستغرق النشر الأول عادة حوالي 10-15 دقيقة؛ عمليات النشر اللاحقة ستكون أسرع + + + ![تقدم النشر](/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/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..cfff6080d --- /dev/null +++ b/docs/ar/installation.mdx @@ -0,0 +1,209 @@ +--- +title: التثبيت +description: ابدأ مع CrewAI - التثبيت والتهيئة وبناء أول فريق AI +icon: wrench +mode: "wide" +--- + +## فيديو تعليمي + +شاهد هذا الفيديو التعليمي لعرض تفصيلي لعملية التثبيت: + + + +## دليل نصي + + + **متطلبات إصدار 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 للمؤسسات وجدول عرضًا توضيحيًا + + + +## الخطوات التالية + + + + اتبع دليل البداية السريعة لإنشاء أول Agent في CrewAI والحصول على تجربة عملية. + + + تواصل مع مطورين آخرين واحصل على المساعدة وشارك تجاربك مع CrewAI. + + diff --git a/docs/ar/introduction.mdx b/docs/ar/introduction.mdx new file mode 100644 index 000000000..46554fc6a --- /dev/null +++ b/docs/ar/introduction.mdx @@ -0,0 +1,144 @@ +--- +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 المعيار لأتمتة الذكاء الاصطناعي الجاهزة للمؤسسات. + +## بنية 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 في بيئة التطوير الخاصة بك. + + + اتبع دليل البداية السريعة لإنشاء أول Agent في CrewAI والحصول على تجربة عملية. + + + تواصل مع مطورين آخرين واحصل على المساعدة وشارك تجاربك مع 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..930ef389f --- /dev/null +++ b/docs/ar/learn/streaming-crew-execution.mdx @@ -0,0 +1,356 @@ +--- +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()) +``` + +## حالات الاستخدام + +البث ذو قيمة خاصة لـ: + +- **التطبيقات التفاعلية**: تقديم تغذية راجعة فورية للمستخدمين أثناء عمل الوكلاء +- **المهام طويلة التشغيل**: عرض التقدم للبحث والتحليل أو توليد المحتوى +- **التصحيح والمراقبة**: مراقبة سلوك الوكلاء واتخاذ القرارات في الوقت الفعلي +- **تجربة المستخدم**: تقليل زمن الاستجابة المتصور بعرض نتائج تدريجية +- **لوحات المعلومات الحية**: بناء واجهات مراقبة تعرض حالة تنفيذ الطاقم + +## ملاحظات مهمة + +- يفعّل البث تلقائياً بث 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..53663c111 --- /dev/null +++ b/docs/ar/learn/streaming-flow-execution.mdx @@ -0,0 +1,450 @@ +--- +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") +``` + +## ملاحظات مهمة + +- يفعّل البث تلقائياً بث 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..679879eb2 --- /dev/null +++ b/docs/ar/quickstart.mdx @@ -0,0 +1,380 @@ +--- +title: البدء السريع +description: ابنِ أول وكيل ذكاء اصطناعي مع CrewAI في أقل من 5 دقائق. +icon: rocket +mode: "wide" +--- + +## ابنِ أول وكيل CrewAI + +لننشئ طاقماً بسيطاً يساعدنا في `البحث` و`إعداد التقارير` عن `أحدث تطورات الذكاء الاصطناعي` لموضوع أو مجال معين. + +قبل المتابعة، تأكد من إنهاء تثبيت CrewAI. +إذا لم تكن قد ثبّتها بعد، يمكنك القيام بذلك باتباع [دليل التثبيت](/ar/installation). + +اتبع الخطوات أدناه للبدء! + + + + أنشئ مشروع طاقم جديد عبر تشغيل الأمر التالي في الطرفية. + سينشئ هذا مجلداً جديداً باسم `latest-ai-development` مع البنية الأساسية لطاقمك. + + ```shell Terminal + crewai create crew latest-ai-development + ``` + + + + + ```shell Terminal + cd latest_ai_development + ``` + + + + + يمكنك أيضاً تعديل الوكلاء حسب الحاجة ليناسبوا حالة الاستخدام الخاصة بك أو نسخ ولصق كما هو في مشروعك. + أي متغير مُستكمل في ملفات `agents.yaml` و`tasks.yaml` مثل `{topic}` سيُستبدل بقيمة المتغير في ملف `main.py`. + + ```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 tasks.yaml + # src/latest_ai_development/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. + 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 + output_file: 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 + from typing import List + + @CrewBase + class LatestAiDevelopmentCrew(): + """LatestAiDevelopment crew""" + + 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 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] + output_file='output/report.md' # This is the file that will be contain the final report. + ) + + @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 + 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""" + + @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 + ``` + + + + على سبيل المثال، يمكنك تمرير مدخل `topic` لطاقمك لتخصيص البحث وإعداد التقارير. + ```python main.py + #!/usr/bin/env python + # src/latest_ai_development/main.py + import sys + from latest_ai_development.crew import LatestAiDevelopmentCrew + + def run(): + """ + Run the crew. + """ + inputs = { + 'topic': 'AI Agents' + } + LatestAiDevelopmentCrew().crew().kickoff(inputs=inputs) + ``` + + + + قبل تشغيل طاقمك، تأكد من تعيين المفاتيح التالية كمتغيرات بيئة في ملف `.env`: + - مفتاح API لـ [Serper.dev](https://serper.dev/): `SERPER_API_KEY=YOUR_KEY_HERE` + - إعداد النموذج الذي اخترته، مثل مفتاح API. راجع + [دليل إعداد LLM](/ar/concepts/llms#setting-up-your-llm) لمعرفة كيفية إعداد النماذج من أي مزود. + + + - اقفل التبعيات وثبّتها باستخدام أمر CLI: + + ```shell Terminal + crewai install + ``` + + - إذا كانت لديك حزم إضافية تريد تثبيتها، يمكنك القيام بذلك عبر: + + ```shell Terminal + uv add + ``` + + + + - لتشغيل طاقمك، نفّذ الأمر التالي في جذر مشروعك: + + ```bash Terminal + crewai run + ``` + + + + + لمستخدمي CrewAI AMP، يمكنك إنشاء نفس الطاقم دون كتابة كود: + +1. سجّل الدخول إلى حساب CrewAI AMP (أنشئ حساباً مجانياً على [app.crewai.com](https://app.crewai.com)) +2. افتح Crew Studio +3. اكتب ما هي الأتمتة التي تحاول بناءها +4. أنشئ مهامك بصرياً واربطها بالتسلسل +5. هيئ مدخلاتك وانقر "تحميل الكود" أو "نشر" + +![واجهة Crew Studio للبدء السريع](/images/enterprise/crew-studio-interface.png) + + + ابدأ حسابك المجاني في CrewAI AMP + + + + يجب أن ترى المخرجات في وحدة التحكم ويجب إنشاء ملف `report.md` في جذر مشروعك مع التقرير النهائي. + +إليك مثالاً على شكل التقرير: + + + ```markdown output/report.md + # Comprehensive Report on the Rise and Impact of AI Agents in 2025 + + ## 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. + ``` + + + + + + +تهانينا! + +لقد أعددت مشروع طاقمك بنجاح وأنت جاهز للبدء في بناء سير العمل الوكيلي الخاص بك! + + + +### ملاحظة حول اتساق التسمية + +يجب أن تتطابق الأسماء التي تستخدمها في ملفات YAML (`agents.yaml` و`tasks.yaml`) مع أسماء الدوال في كود Python الخاص بك. +على سبيل المثال، يمكنك الإشارة إلى الوكيل لمهام محددة من ملف `tasks.yaml`. +يتيح اتساق التسمية هذا لـ CrewAI ربط تكويناتك بكودك تلقائياً؛ وإلا فلن تتعرف مهمتك على المرجع بشكل صحيح. + +#### أمثلة على المراجع + + + لاحظ كيف نستخدم نفس الاسم للوكيل في ملف `agents.yaml` + (`email_summarizer`) واسم الدالة في ملف `crew.py` + (`email_summarizer`). + + +```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 +``` + + + لاحظ كيف نستخدم نفس الاسم للمهمة في ملف `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 +``` + +## نشر طاقمك + +أسهل طريقة لنشر طاقمك في الإنتاج هي من خلال [CrewAI AMP](http://app.crewai.com). + +شاهد هذا الفيديو التعليمي لعرض خطوة بخطوة لنشر طاقمك على [CrewAI AMP](http://app.crewai.com) باستخدام CLI. + + + + + + ابدأ مع CrewAI AMP وانشر طاقمك في بيئة إنتاج + بنقرات قليلة فقط. + + + انضم إلى مجتمعنا مفتوح المصدر لمناقشة الأفكار ومشاركة مشاريعك والتواصل + مع مطورين آخرين لـ CrewAI. + + diff --git a/docs/ar/snippets/snippet-intro.mdx b/docs/ar/snippets/snippet-intro.mdx new file mode 100644 index 000000000..d61d5b16c --- /dev/null +++ b/docs/ar/snippets/snippet-intro.mdx @@ -0,0 +1 @@ +أحد المبادئ الأساسية في تطوير البرمجيات هو مبدأ DRY (لا تكرر نفسك). هذا مبدأ ينطبق على التوثيق أيضاً. إذا وجدت نفسك تكرر نفس المحتوى في أماكن متعددة، يجب أن تفكر في إنشاء مقتطف مخصص للحفاظ على تزامن محتواك. diff --git a/docs/ar/telemetry.mdx b/docs/ar/telemetry.mdx new file mode 100644 index 000000000..0cc017ae9 --- /dev/null +++ b/docs/ar/telemetry.mdx @@ -0,0 +1,68 @@ +--- +title: القياس عن بُعد +description: فهم بيانات القياس عن بُعد التي يجمعها CrewAI وكيف تساهم في تحسين المكتبة. +icon: signal-stream +mode: "wide" +--- + +## القياس عن بُعد + + + بشكل افتراضي، لا نجمع أي بيانات تُعتبر معلومات شخصية بموجب اللائحة العامة لحماية البيانات (GDPR) وغيرها من لوائح الخصوصية. + نحن نجمع أسماء الأدوات وأدوار الوكلاء، لذا يُنصح بعدم تضمين أي معلومات شخصية في أسماء الأدوات أو أدوار الوكلاء. + نظراً لعدم جمع معلومات شخصية، ليس من الضروري القلق بشأن إقامة البيانات. + عند تفعيل `share_crew`، يتم جمع بيانات إضافية قد تحتوي على معلومات شخصية إذا ضمّنها المستخدم. + يجب على المستخدمين توخي الحذر عند تفعيل هذه الميزة لضمان الامتثال للوائح الخصوصية. + + +يستخدم CrewAI القياس عن بُعد المجهول لجمع إحصائيات الاستخدام بهدف أساسي هو تحسين المكتبة. +تركيزنا ينصبّ على تحسين وتطوير الميزات والتكاملات والأدوات الأكثر استخداماً من قبل مستخدمينا. + +من المهم فهم أنه بشكل افتراضي، **لا يتم جمع أي بيانات شخصية** تتعلق بالموجهات أو أوصاف المهام أو خلفيات الوكلاء أو أهدافهم، +أو استخدام الأدوات أو استدعاءات API أو الاستجابات أو أي بيانات يعالجها الوكلاء أو الأسرار ومتغيرات البيئة. +عند تفعيل ميزة `share_crew`، يتم جمع بيانات تفصيلية تشمل أوصاف المهام وخلفيات وأهداف الوكلاء وسمات محددة أخرى +لتوفير رؤى أعمق. قد يتضمن جمع البيانات الموسع هذا معلومات شخصية إذا دمجها المستخدمون في طواقمهم أو مهامهم. +يجب على المستخدمين النظر بعناية في محتوى طواقمهم ومهامهم قبل تفعيل `share_crew`. +يمكن للمستخدمين تعطيل القياس عن بُعد عبر تعيين متغير البيئة `CREWAI_DISABLE_TELEMETRY` إلى `true` أو تعيين `OTEL_SDK_DISABLED` إلى `true` (لاحظ أن الأخير يعطل جميع أدوات OpenTelemetry عالمياً). + +### أمثلة: +```python +# Disable CrewAI telemetry only +os.environ['CREWAI_DISABLE_TELEMETRY'] = 'true' + +# Disable all OpenTelemetry (including CrewAI) +os.environ['OTEL_SDK_DISABLED'] = 'true' +``` + +### شرح البيانات: +| افتراضي | البيانات | السبب والتفاصيل | +|:----------|:------------------------------------------|:----------------------------------------------------------------------------------------------------------------------------| +| نعم | إصدار CrewAI وPython | تتبع إصدارات البرمجيات. مثال: CrewAI v1.2.3، Python 3.8.10. لا بيانات شخصية. | +| نعم | بيانات وصفية للطاقم | تشمل: مفتاح ومعرّف مُولّد عشوائياً، نوع العملية (مثل 'sequential'، 'parallel')، علم منطقي لاستخدام الذاكرة (true/false)، عدد المهام، عدد الوكلاء. كلها غير شخصية. | +| نعم | بيانات الوكيل | تشمل: مفتاح ومعرّف مُولّد عشوائياً، اسم الدور (يجب ألا يتضمن معلومات شخصية)، إعدادات منطقية (verbose، التفويض مُفعّل، تنفيذ الكود مسموح)، أقصى عدد تكرارات، أقصى RPM، أقصى حد لإعادة المحاولة، معلومات LLM (انظر سمات LLM)، قائمة أسماء الأدوات (يجب ألا تتضمن معلومات شخصية). لا بيانات شخصية. | +| نعم | بيانات وصفية للمهمة | تشمل: مفتاح ومعرّف مُولّد عشوائياً، إعدادات تنفيذ منطقية (async_execution، human_input)، دور ومفتاح الوكيل المرتبط، قائمة أسماء الأدوات. كلها غير شخصية. | +| نعم | إحصائيات استخدام الأدوات | تشمل: اسم الأداة (يجب ألا يتضمن معلومات شخصية)، عدد محاولات الاستخدام (عدد صحيح)، سمات LLM المستخدمة. لا بيانات شخصية. | +| نعم | بيانات تنفيذ الاختبار | تشمل: مفتاح ومعرّف الطاقم المُولّد عشوائياً، عدد التكرارات، اسم النموذج المستخدم، درجة الجودة (عدد عشري)، وقت التنفيذ (بالثواني). كلها غير شخصية. | +| نعم | بيانات دورة حياة المهمة | تشمل: أوقات الإنشاء وبدء/انتهاء التنفيذ، معرّفات الطاقم والمهمة. مخزنة كنطاقات مع طوابع زمنية. لا بيانات شخصية. | +| نعم | سمات LLM | تشمل: الاسم، model_name، model، top_k، temperature، واسم فئة LLM. كلها بيانات تقنية غير شخصية. | +| نعم | محاولة نشر الطاقم باستخدام CLI الخاص بـ CrewAI | تشمل: حقيقة إجراء النشر ومعرّف الطاقم، وما إذا كان يحاول سحب السجلات، لا بيانات أخرى. | +| لا | بيانات الوكيل الموسّعة | تشمل: وصف الهدف، نص الخلفية، معرّف ملف موجهات i18n. يجب على المستخدمين التأكد من عدم تضمين معلومات شخصية في حقول النص. | +| لا | معلومات المهمة التفصيلية | تشمل: وصف المهمة، وصف المخرجات المتوقعة، مراجع السياق. يجب على المستخدمين التأكد من عدم تضمين معلومات شخصية في هذه الحقول. | +| لا | معلومات البيئة | تشمل: المنصة، الإصدار، النظام، الإصدار، وعدد وحدات المعالجة المركزية. مثال: 'Windows 10'، 'x86_64'. لا بيانات شخصية. | +| لا | مدخلات ومخرجات الطاقم والمهام | تشمل: معاملات الإدخال ونتائج المخرجات كبيانات غير قابلة للتعريف. يجب على المستخدمين التأكد من عدم تضمين معلومات شخصية. | +| لا | بيانات تنفيذ الطاقم الشاملة | تشمل: سجلات مفصّلة لعمليات الطاقم، جميع بيانات الوكلاء والمهام، المخرجات النهائية. كلها غير شخصية وتقنية بطبيعتها. | + + + "لا" في عمود "افتراضي" تشير إلى أن هذه البيانات تُجمع فقط عند تعيين `share_crew` إلى `true`. + + +### الاشتراك في مشاركة قياس عن بُعد إضافية + +يمكن للمستخدمين اختيار مشاركة بيانات القياس عن بُعد الكاملة عبر تفعيل سمة `share_crew` إلى `True` في تكوينات طواقمهم. +تفعيل `share_crew` يؤدي إلى جمع بيانات تفصيلية لتنفيذ الطاقم والمهام، بما في ذلك `goal` و`backstory` و`context` و`output` للمهام. +يتيح هذا رؤية أعمق لأنماط الاستخدام. + + + إذا فعّلت `share_crew`، فقد تتضمن البيانات المجمعة معلومات شخصية إذا تم دمجها في تكوينات الطاقم أو أوصاف المهام أو المخرجات. + يجب على المستخدمين مراجعة بياناتهم بعناية وضمان الامتثال للائحة العامة لحماية البيانات (GDPR) وغيرها من لوائح الخصوصية المعمول بها قبل تفعيل هذه الميزة. + diff --git a/docs/ar/tools/ai-ml/aimindtool.mdx b/docs/ar/tools/ai-ml/aimindtool.mdx new file mode 100644 index 000000000..a900e78d3 --- /dev/null +++ b/docs/ar/tools/ai-ml/aimindtool.mdx @@ -0,0 +1,119 @@ +--- +title: أداة AI Mind +description: أداة `AIMindTool` مصممة للاستعلام عن مصادر البيانات باللغة الطبيعية. +icon: brain +mode: "wide" +--- + +# `AIMindTool` + +## الوصف + +أداة `AIMindTool` هي غلاف حول [AI-Minds](https://mindsdb.com/minds) المقدمة من [MindsDB](https://mindsdb.com/). تتيح لك الاستعلام عن مصادر البيانات باللغة الطبيعية ببساطة من خلال إعداد معاملات الاتصال الخاصة بها. هذه الأداة مفيدة عندما تحتاج إلى إجابات عن أسئلة من بياناتك المخزنة في مصادر بيانات متنوعة بما في ذلك PostgreSQL وMySQL وMariaDB وClickHouse وSnowflake وGoogle BigQuery. + +Minds هي أنظمة ذكاء اصطناعي تعمل بشكل مشابه لنماذج اللغة الكبيرة (LLMs) لكنها تتجاوز ذلك من خلال الإجابة على أي سؤال من أي بيانات. يتحقق ذلك من خلال: +- اختيار البيانات الأكثر صلة للإجابة باستخدام البحث البارامتري +- فهم المعنى وتقديم الاستجابات ضمن السياق الصحيح من خلال البحث الدلالي +- تقديم إجابات دقيقة من خلال تحليل البيانات واستخدام نماذج التعلم الآلي (ML) + +## التثبيت + +لدمج هذه الأداة في مشروعك، تحتاج إلى تثبيت Minds SDK: + +```shell +uv add minds-sdk +``` + +## خطوات البدء + +لاستخدام `AIMindTool` بفعالية، اتبع الخطوات التالية: + +1. **تثبيت الحزمة**: تأكد من تثبيت حزمتي `crewai[tools]` و`minds-sdk` في بيئة Python. +2. **الحصول على مفتاح API**: سجّل في حساب Minds [هنا](https://mdb.ai/register)، واحصل على مفتاح API. +3. **إعداد البيئة**: خزّن مفتاح API الذي حصلت عليه في متغير بيئة باسم `MINDS_API_KEY` لتسهيل استخدامه من قبل الأداة. + +## مثال + +يوضح المثال التالي كيفية تهيئة الأداة وتنفيذ استعلام: + +```python Code +from crewai_tools import AIMindTool + +# Initialize the AIMindTool +aimind_tool = AIMindTool( + datasources=[ + { + "description": "house sales data", + "engine": "postgres", + "connection_data": { + "user": "demo_user", + "password": "demo_password", + "host": "samples.mindsdb.com", + "port": 5432, + "database": "demo", + "schema": "demo_data" + }, + "tables": ["house_sales"] + } + ] +) + +# Run a natural language query +result = aimind_tool.run("How many 3 bedroom houses were sold in 2008?") +print(result) +``` + +## المعاملات + +تقبل `AIMindTool` المعاملات التالية: + +- **api_key**: اختياري. مفتاح API الخاص بـ Minds. إذا لم يُقدَّم، سيُقرأ من متغير البيئة `MINDS_API_KEY`. +- **datasources**: قائمة من القواميس، كل منها يحتوي على المفاتيح التالية: + - **description**: وصف البيانات الموجودة في مصدر البيانات. + - **engine**: محرك (أو نوع) مصدر البيانات. + - **connection_data**: قاموس يحتوي على معاملات الاتصال لمصدر البيانات. + - **tables**: قائمة الجداول التي سيستخدمها مصدر البيانات. هذا اختياري ويمكن حذفه إذا كانت جميع الجداول في مصدر البيانات مطلوبة. + +يمكن العثور على قائمة مصادر البيانات المدعومة ومعاملات اتصالها [هنا](https://docs.mdb.ai/docs/data_sources). + +## مثال على التكامل مع الوكيل + +إليك كيفية دمج `AIMindTool` مع وكيل CrewAI: + +```python Code +from crewai import Agent +from crewai.project import agent +from crewai_tools import AIMindTool + +# Initialize the tool +aimind_tool = AIMindTool( + datasources=[ + { + "description": "sales data", + "engine": "postgres", + "connection_data": { + "user": "your_user", + "password": "your_password", + "host": "your_host", + "port": 5432, + "database": "your_db", + "schema": "your_schema" + }, + "tables": ["sales"] + } + ] +) + +# Define an agent with the AIMindTool +@agent +def data_analyst(self) -> Agent: + return Agent( + config=self.agents_config["data_analyst"], + allow_delegation=False, + tools=[aimind_tool] + ) +``` + +## الخلاصة + +توفر `AIMindTool` طريقة قوية للاستعلام عن مصادر بياناتك باستخدام اللغة الطبيعية، مما يسهّل استخراج الرؤى دون كتابة استعلامات SQL معقدة. من خلال الاتصال بمصادر بيانات متنوعة والاستفادة من تقنية AI-Minds، تمكّن هذه الأداة الوكلاء من الوصول إلى البيانات وتحليلها بكفاءة. diff --git a/docs/ar/tools/ai-ml/codeinterpretertool.mdx b/docs/ar/tools/ai-ml/codeinterpretertool.mdx new file mode 100644 index 000000000..dbcf016eb --- /dev/null +++ b/docs/ar/tools/ai-ml/codeinterpretertool.mdx @@ -0,0 +1,210 @@ +--- +title: مفسّر الكود +description: أداة `CodeInterpreterTool` هي أداة قوية مصممة لتنفيذ كود Python 3 في بيئة آمنة ومعزولة. +icon: code-simple +mode: "wide" +--- + +# `CodeInterpreterTool` + +## الوصف + +تمكّن `CodeInterpreterTool` وكلاء CrewAI من تنفيذ كود Python 3 الذي يولّدونه بشكل مستقل. هذه الوظيفة ذات قيمة خاصة لأنها تتيح للوكلاء إنشاء الكود وتنفيذه والحصول على النتائج واستخدام تلك المعلومات لاتخاذ القرارات والإجراءات اللاحقة. + +هناك عدة طرق لاستخدام هذه الأداة: + +### حاوية Docker (موصى بها) + +هذا هو الخيار الأساسي. يُنفَّذ الكود في حاوية Docker آمنة ومعزولة، مما يضمن السلامة بغض النظر عن محتواه. +تأكد من تثبيت Docker وتشغيله على نظامك. إذا لم يكن لديك، يمكنك تثبيته من [هنا](https://docs.docker.com/get-docker/). + +### بيئة الحماية + +إذا لم يكن Docker متاحاً - إما غير مُثبّت أو غير قابل للوصول لأي سبب - سيُنفَّذ الكود في بيئة Python مقيدة تُسمى بيئة الحماية. +هذه البيئة محدودة جداً، مع قيود صارمة على العديد من الوحدات والدوال المدمجة. + +### التنفيذ غير الآمن + +**غير موصى به للإنتاج** +يسمح هذا الوضع بتنفيذ أي كود Python، بما في ذلك الاستدعاءات الخطيرة لـ `sys, os..` والوحدات المماثلة. [اطلع على](/ar/tools/ai-ml/codeinterpretertool#enabling-unsafe-mode) كيفية تفعيل هذا الوضع + +## التسجيل + +تسجّل `CodeInterpreterTool` استراتيجية التنفيذ المختارة في STDOUT + + +## التثبيت + +لاستخدام هذه الأداة، تحتاج إلى تثبيت حزمة أدوات CrewAI: + +```shell +pip install 'crewai[tools]' +``` + +## مثال + +يوضح المثال التالي كيفية استخدام `CodeInterpreterTool` مع وكيل CrewAI: + +```python Code +from crewai import Agent, Task, Crew, Process +from crewai_tools import CodeInterpreterTool + +# Initialize the tool +code_interpreter = CodeInterpreterTool() + +# Define an agent that uses the tool +programmer_agent = Agent( + role="Python Programmer", + goal="Write and execute Python code to solve problems", + backstory="An expert Python programmer who can write efficient code to solve complex problems.", + tools=[code_interpreter], + verbose=True, +) + +# Example task to generate and execute code +coding_task = Task( + description="Write a Python function to calculate the Fibonacci sequence up to the 10th number and print the result.", + expected_output="The Fibonacci sequence up to the 10th number.", + agent=programmer_agent, +) + +# Create and run the crew +crew = Crew( + agents=[programmer_agent], + tasks=[coding_task], + verbose=True, + process=Process.sequential, +) +result = crew.kickoff() +``` + +يمكنك أيضاً تفعيل تنفيذ الكود مباشرة عند إنشاء وكيل: + +```python Code +from crewai import Agent + +# Create an agent with code execution enabled +programmer_agent = Agent( + role="Python Programmer", + goal="Write and execute Python code to solve problems", + backstory="An expert Python programmer who can write efficient code to solve complex problems.", + allow_code_execution=True, # This automatically adds the CodeInterpreterTool + verbose=True, +) +``` + +### تفعيل `unsafe_mode` + +```python Code +from crewai_tools import CodeInterpreterTool + +code = """ +import os +os.system("ls -la") +""" + +CodeInterpreterTool(unsafe_mode=True).run(code=code) +``` + +## المعاملات + +تقبل `CodeInterpreterTool` المعاملات التالية أثناء التهيئة: + +- **user_dockerfile_path**: اختياري. مسار ملف Dockerfile مخصص لاستخدامه لحاوية مفسّر الكود. +- **user_docker_base_url**: اختياري. عنوان URL لبرنامج Docker daemon لتشغيل الحاوية. +- **unsafe_mode**: اختياري. ما إذا كان سيتم تشغيل الكود مباشرة على الجهاز المضيف بدلاً من حاوية Docker أو بيئة الحماية. القيمة الافتراضية `False`. استخدم بحذر! +- **default_image_tag**: اختياري. وسم صورة Docker الافتراضي. القيمة الافتراضية `code-interpreter:latest` + +عند استخدام الأداة مع وكيل، سيحتاج الوكيل لتقديم: + +- **code**: مطلوب. كود Python 3 المراد تنفيذه. +- **libraries_used**: اختياري. قائمة المكتبات المستخدمة في الكود التي تحتاج إلى تثبيت. القيمة الافتراضية `[]` + +## مثال على التكامل مع الوكيل + +إليك مثالاً أكثر تفصيلاً عن كيفية دمج `CodeInterpreterTool` مع وكيل CrewAI: + +```python Code +from crewai import Agent, Task, Crew +from crewai_tools import CodeInterpreterTool + +# Initialize the tool +code_interpreter = CodeInterpreterTool() + +# Define an agent that uses the tool +data_analyst = Agent( + role="Data Analyst", + goal="Analyze data using Python code", + backstory="""You are an expert data analyst who specializes in using Python + to analyze and visualize data. You can write efficient code to process + large datasets and extract meaningful insights.""", + tools=[code_interpreter], + verbose=True, +) + +# Create a task for the agent +analysis_task = Task( + description=""" + Write Python code to: + 1. Generate a random dataset of 100 points with x and y coordinates + 2. Calculate the correlation coefficient between x and y + 3. Create a scatter plot of the data + 4. Print the correlation coefficient and save the plot as 'scatter.png' + + Make sure to handle any necessary imports and print the results. + """, + expected_output="The correlation coefficient and confirmation that the scatter plot has been saved.", + agent=data_analyst, +) + +# Run the task +crew = Crew( + agents=[data_analyst], + tasks=[analysis_task], + verbose=True, + process=Process.sequential, +) +result = crew.kickoff() +``` + +## تفاصيل التنفيذ + +تستخدم `CodeInterpreterTool` حاوية Docker لإنشاء بيئة آمنة لتنفيذ الكود: + +```python Code +class CodeInterpreterTool(BaseTool): + name: str = "Code Interpreter" + description: str = "Interprets Python3 code strings with a final print statement." + args_schema: Type[BaseModel] = CodeInterpreterSchema + default_image_tag: str = "code-interpreter:latest" + + def _run(self, **kwargs) -> str: + code = kwargs.get("code", self.code) + libraries_used = kwargs.get("libraries_used", []) + + if self.unsafe_mode: + return self.run_code_unsafe(code, libraries_used) + else: + return self.run_code_safety(code, libraries_used) +``` + +تقوم الأداة بالخطوات التالية: +1. التحقق من وجود صورة Docker أو بنائها إذا لزم الأمر +2. إنشاء حاوية Docker مع تركيب مجلد العمل الحالي +3. تثبيت أي مكتبات مطلوبة حددها الوكيل +4. تنفيذ كود Python في الحاوية +5. إرجاع مخرجات تنفيذ الكود +6. التنظيف عن طريق إيقاف الحاوية وإزالتها + +## اعتبارات الأمان + +بشكل افتراضي، تشغّل `CodeInterpreterTool` الكود في حاوية Docker معزولة، مما يوفر طبقة من الأمان. ومع ذلك، هناك بعض اعتبارات الأمان التي يجب مراعاتها: + +1. تمتلك حاوية Docker وصولاً إلى مجلد العمل الحالي، لذا قد يتم الوصول إلى ملفات حساسة. +2. إذا لم تكن حاوية Docker متاحة وكان الكود يحتاج للتشغيل بأمان، سيُنفَّذ في بيئة حماية. لأسباب أمنية، لا يُسمح بتثبيت مكتبات عشوائية +3. يسمح معامل `unsafe_mode` بتنفيذ الكود مباشرة على الجهاز المضيف، ويجب استخدامه فقط في بيئات موثوقة. +4. كن حذراً عند السماح للوكلاء بتثبيت مكتبات عشوائية، لأنها قد تتضمن كوداً ضاراً. + +## الخلاصة + +توفر `CodeInterpreterTool` طريقة قوية لوكلاء CrewAI لتنفيذ كود Python في بيئة آمنة نسبياً. من خلال تمكين الوكلاء من كتابة وتشغيل الكود، توسّع قدراتهم في حل المشكلات بشكل كبير، خاصة للمهام التي تتضمن تحليل البيانات أو الحسابات أو أعمال حسابية أخرى. هذه الأداة مفيدة بشكل خاص للوكلاء الذين يحتاجون إلى إجراء عمليات معقدة يُعبَّر عنها بكفاءة أكبر في الكود مقارنة باللغة الطبيعية. diff --git a/docs/ar/tools/ai-ml/dalletool.mdx b/docs/ar/tools/ai-ml/dalletool.mdx new file mode 100644 index 000000000..2caa13b5c --- /dev/null +++ b/docs/ar/tools/ai-ml/dalletool.mdx @@ -0,0 +1,52 @@ +--- +title: أداة DALL-E +description: أداة `DallETool` هي أداة قوية مصممة لتوليد الصور من الأوصاف النصية. +icon: image +mode: "wide" +--- + +# `DallETool` + +## الوصف + +تُستخدم هذه الأداة لمنح الوكيل القدرة على توليد الصور باستخدام نموذج DALL-E. وهو نموذج قائم على المحولات يولّد الصور من الأوصاف النصية. +تتيح هذه الأداة للوكيل توليد صور بناءً على النص المدخل من المستخدم. + +## التثبيت + +ثبّت حزمة crewai_tools +```shell +pip install 'crewai[tools]' +``` + +## مثال + +تذكر أنه عند استخدام هذه الأداة، يجب أن يُولَّد النص من قبل الوكيل نفسه. يجب أن يكون النص وصفاً للصورة التي تريد توليدها. + +```python Code +from crewai_tools import DallETool + +Agent( + ... + tools=[DallETool()], +) +``` + +إذا لزم الأمر، يمكنك أيضاً ضبط معاملات نموذج DALL-E عبر تمريرها كمعاملات لفئة `DallETool`. على سبيل المثال: + +```python Code +from crewai_tools import DallETool + +dalle_tool = DallETool(model="dall-e-3", + size="1024x1024", + quality="standard", + n=1) + +Agent( + ... + tools=[dalle_tool] +) +``` + +المعاملات مبنية على طريقة `client.images.generate` من API الخاص بـ OpenAI. لمزيد من المعلومات حول المعاملات، +يرجى الرجوع إلى [وثائق OpenAI API](https://platform.openai.com/docs/guides/images/introduction?lang=python). diff --git a/docs/ar/tools/ai-ml/langchaintool.mdx b/docs/ar/tools/ai-ml/langchaintool.mdx new file mode 100644 index 000000000..550ea0823 --- /dev/null +++ b/docs/ar/tools/ai-ml/langchaintool.mdx @@ -0,0 +1,59 @@ +--- +title: أداة LangChain +description: أداة `LangChainTool` هي غلاف لأدوات ومحركات استعلام LangChain. +icon: link +mode: "wide" +--- + +## `LangChainTool` + + + يتكامل CrewAI بسلاسة مع [قائمة أدوات](https://python.langchain.com/docs/integrations/tools/) LangChain الشاملة، والتي يمكن استخدامها جميعها مع CrewAI. + + +```python Code +import os +from dotenv import load_dotenv +from crewai import Agent, Task, Crew +from crewai.tools import BaseTool +from pydantic import Field +from langchain_community.utilities import GoogleSerperAPIWrapper + +# Set up your SERPER_API_KEY key in an .env file, eg: +# SERPER_API_KEY= +load_dotenv() + +search = GoogleSerperAPIWrapper() + +class SearchTool(BaseTool): + name: str = "Search" + description: str = "Useful for search-based queries. Use this to find current information about markets, companies, and trends." + search: GoogleSerperAPIWrapper = Field(default_factory=GoogleSerperAPIWrapper) + + def _run(self, query: str) -> str: + """Execute the search query and return results""" + try: + return self.search.run(query) + except Exception as e: + return f"Error performing search: {str(e)}" + +# Create Agents +researcher = Agent( + role='Research Analyst', + goal='Gather current market data and trends', + backstory="""You are an expert research analyst with years of experience in + gathering market intelligence. You're known for your ability to find + relevant and up-to-date market information and present it in a clear, + actionable format.""", + tools=[SearchTool()], + verbose=True +) + +# rest of the code ... +``` + +## الخلاصة + +تعد الأدوات محورية في توسيع قدرات وكلاء CrewAI، مما يمكّنهم من القيام بمجموعة واسعة من المهام والتعاون بفعالية. +عند بناء حلول مع CrewAI، استفد من الأدوات المخصصة والموجودة لتمكين وكلائك وتعزيز منظومة الذكاء الاصطناعي. فكّر في الاستفادة من معالجة الأخطاء وآليات التخزين المؤقت +ومرونة معاملات الأدوات لتحسين أداء وقدرات وكلائك. diff --git a/docs/ar/tools/ai-ml/llamaindextool.mdx b/docs/ar/tools/ai-ml/llamaindextool.mdx new file mode 100644 index 000000000..91625856b --- /dev/null +++ b/docs/ar/tools/ai-ml/llamaindextool.mdx @@ -0,0 +1,147 @@ +--- +title: أداة LlamaIndex +description: أداة `LlamaIndexTool` هي غلاف لأدوات ومحركات استعلام LlamaIndex. +icon: address-book +mode: "wide" +--- + +# `LlamaIndexTool` + +## الوصف + +صُممت `LlamaIndexTool` لتكون غلافاً عاماً حول أدوات ومحركات استعلام LlamaIndex، مما يتيح لك الاستفادة من موارد LlamaIndex من حيث خطوط أنابيب RAG/الوكيلية كأدوات للتوصيل بوكلاء CrewAI. تتيح لك هذه الأداة دمج قدرات معالجة واسترجاع البيانات القوية من LlamaIndex في سير عمل CrewAI بسلاسة. + +## التثبيت + +لاستخدام هذه الأداة، تحتاج إلى تثبيت LlamaIndex: + +```shell +uv add llama-index +``` + +## خطوات البدء + +لاستخدام `LlamaIndexTool` بفعالية، اتبع الخطوات التالية: + +1. **تثبيت LlamaIndex**: ثبّت حزمة LlamaIndex باستخدام الأمر أعلاه. +2. **إعداد LlamaIndex**: اتبع [وثائق LlamaIndex](https://docs.llamaindex.ai/) لإعداد خط أنابيب RAG/وكيلي. +3. **إنشاء أداة أو محرك استعلام**: أنشئ أداة أو محرك استعلام LlamaIndex تريد استخدامه مع CrewAI. + +## مثال + +توضح الأمثلة التالية كيفية تهيئة الأداة من مكونات LlamaIndex مختلفة: + +### من أداة LlamaIndex + +```python Code +from crewai_tools import LlamaIndexTool +from crewai import Agent +from llama_index.core.tools import FunctionTool + +# Example 1: Initialize from FunctionTool +def search_data(query: str) -> str: + """Search for information in the data.""" + # Your implementation here + return f"Results for: {query}" + +# Create a LlamaIndex FunctionTool +og_tool = FunctionTool.from_defaults( + search_data, + name="DataSearchTool", + description="Search for information in the data" +) + +# Wrap it with LlamaIndexTool +tool = LlamaIndexTool.from_tool(og_tool) + +# Define an agent that uses the tool +@agent +def researcher(self) -> Agent: + ''' + This agent uses the LlamaIndexTool to search for information. + ''' + return Agent( + config=self.agents_config["researcher"], + tools=[tool] + ) +``` + +### من أدوات LlamaHub + +```python Code +from crewai_tools import LlamaIndexTool +from llama_index.tools.wolfram_alpha import WolframAlphaToolSpec + +# Initialize from LlamaHub Tools +wolfram_spec = WolframAlphaToolSpec(app_id="your_app_id") +wolfram_tools = wolfram_spec.to_tool_list() +tools = [LlamaIndexTool.from_tool(t) for t in wolfram_tools] +``` + +### من محرك استعلام LlamaIndex + +```python Code +from crewai_tools import LlamaIndexTool +from llama_index.core import VectorStoreIndex +from llama_index.core.readers import SimpleDirectoryReader + +# Load documents +documents = SimpleDirectoryReader("./data").load_data() + +# Create an index +index = VectorStoreIndex.from_documents(documents) + +# Create a query engine +query_engine = index.as_query_engine() + +# Create a LlamaIndexTool from the query engine +query_tool = LlamaIndexTool.from_query_engine( + query_engine, + name="Company Data Query Tool", + description="Use this tool to lookup information in company documents" +) +``` + +## طرق الفئة + +توفر `LlamaIndexTool` طريقتي فئة رئيسيتين لإنشاء المثيلات: + +### from_tool + +تنشئ `LlamaIndexTool` من أداة LlamaIndex. + +```python Code +@classmethod +def from_tool(cls, tool: Any, **kwargs: Any) -> "LlamaIndexTool": + # Implementation details +``` + +### from_query_engine + +تنشئ `LlamaIndexTool` من محرك استعلام LlamaIndex. + +```python Code +@classmethod +def from_query_engine( + cls, + query_engine: Any, + name: Optional[str] = None, + description: Optional[str] = None, + return_direct: bool = False, + **kwargs: Any, +) -> "LlamaIndexTool": + # Implementation details +``` + +## المعاملات + +تقبل طريقة `from_query_engine` المعاملات التالية: + +- **query_engine**: مطلوب. محرك استعلام LlamaIndex المراد تغليفه. +- **name**: اختياري. اسم الأداة. +- **description**: اختياري. وصف الأداة. +- **return_direct**: اختياري. ما إذا كان يتم إرجاع الاستجابة مباشرة. القيمة الافتراضية `False`. + +## الخلاصة + +توفر `LlamaIndexTool` طريقة قوية لدمج قدرات LlamaIndex في وكلاء CrewAI. من خلال تغليف أدوات ومحركات استعلام LlamaIndex، تمكّن الوكلاء من الاستفادة من وظائف استرجاع ومعالجة البيانات المتطورة، مما يعزز قدرتهم على التعامل مع مصادر المعلومات المعقدة. diff --git a/docs/ar/tools/ai-ml/overview.mdx b/docs/ar/tools/ai-ml/overview.mdx new file mode 100644 index 000000000..a3d905d8b --- /dev/null +++ b/docs/ar/tools/ai-ml/overview.mdx @@ -0,0 +1,65 @@ +--- +title: "نظرة عامة" +description: "استفد من خدمات الذكاء الاصطناعي وولّد الصور وعالج الرؤية وابنِ أنظمة ذكية" +icon: "face-smile" +mode: "wide" +--- + +تتكامل هذه الأدوات مع خدمات الذكاء الاصطناعي وتعلم الآلة لتعزيز وكلائك بقدرات متقدمة مثل توليد الصور ومعالجة الرؤية وتنفيذ الكود الذكي. + +## **الأدوات المتاحة** + + + + توليد صور بالذكاء الاصطناعي باستخدام نموذج DALL-E من OpenAI. + + + + معالجة وتحليل الصور بقدرات الرؤية الحاسوبية. + + + + قدرات متقدمة للتفكير واتخاذ القرار بالذكاء الاصطناعي. + + + + بناء قواعد معرفية وأنظمة استرجاع مع LlamaIndex. + + + + التكامل مع LangChain لسير عمل ذكاء اصطناعي معقدة. + + + + تنفيذ أنظمة التوليد المعزز بالاسترجاع. + + + + تنفيذ كود Python وإجراء تحليل البيانات. + + + + + +## **حالات الاستخدام الشائعة** + +- **توليد المحتوى**: إنشاء صور ونصوص ومحتوى وسائط متعددة +- **تحليل البيانات**: تنفيذ الكود وتحليل مجموعات بيانات معقدة +- **أنظمة المعرفة**: بناء أنظمة RAG وقواعد بيانات ذكية +- **الرؤية الحاسوبية**: معالجة وفهم المحتوى المرئي +- **سلامة الذكاء الاصطناعي**: تنفيذ فحوصات الإشراف على المحتوى والسلامة + +```python +from crewai_tools import DallETool, VisionTool, CodeInterpreterTool + +# Create AI tools +image_generator = DallETool() +vision_processor = VisionTool() +code_executor = CodeInterpreterTool() + +# Add to your agent +agent = Agent( + role="AI Specialist", + tools=[image_generator, vision_processor, code_executor], + goal="Create and analyze content using AI capabilities" +) diff --git a/docs/ar/tools/ai-ml/ragtool.mdx b/docs/ar/tools/ai-ml/ragtool.mdx new file mode 100644 index 000000000..a73709b69 --- /dev/null +++ b/docs/ar/tools/ai-ml/ragtool.mdx @@ -0,0 +1,654 @@ +--- +title: أداة RAG +description: أداة `RagTool` هي أداة قاعدة معرفية ديناميكية للإجابة على الأسئلة باستخدام التوليد المعزز بالاسترجاع. +icon: vector-square +mode: "wide" +--- + +# `RagTool` + +## الوصف + +صُممت `RagTool` للإجابة على الأسئلة من خلال الاستفادة من قوة التوليد المعزز بالاسترجاع (RAG) عبر نظام RAG الأصلي في CrewAI. +توفر قاعدة معرفية ديناميكية يمكن الاستعلام عنها لاسترجاع المعلومات ذات الصلة من مصادر بيانات متنوعة. +هذه الأداة مفيدة بشكل خاص للتطبيقات التي تتطلب الوصول إلى مجموعة واسعة من المعلومات وتحتاج إلى تقديم إجابات ذات صلة بالسياق. + +## مثال + +يوضح المثال التالي كيفية تهيئة الأداة واستخدامها مع مصادر بيانات مختلفة: + +```python Code +from crewai_tools import RagTool + +# Create a RAG tool with default settings +rag_tool = RagTool() + +# Add content from a file +rag_tool.add(data_type="file", path="path/to/your/document.pdf") + +# Add content from a web page +rag_tool.add(data_type="web_page", url="https://example.com") + +# Define an agent with the RagTool +@agent +def knowledge_expert(self) -> Agent: + ''' + This agent uses the RagTool to answer questions about the knowledge base. + ''' + return Agent( + config=self.agents_config["knowledge_expert"], + allow_delegation=False, + tools=[rag_tool] + ) +``` + +## مصادر البيانات المدعومة + +يمكن استخدام `RagTool` مع مجموعة واسعة من مصادر البيانات، بما في ذلك: + +- ملفات PDF +- ملفات CSV +- ملفات JSON +- نصوص +- مجلدات/أدلة +- صفحات ويب HTML +- قنوات YouTube +- فيديوهات YouTube +- مواقع التوثيق +- ملفات MDX +- ملفات DOCX +- ملفات XML +- Gmail +- مستودعات GitHub +- قواعد بيانات PostgreSQL +- قواعد بيانات MySQL +- محادثات Slack +- رسائل Discord +- منتديات Discourse +- نشرات Substack +- محتوى Beehiiv +- ملفات Dropbox +- صور +- مصادر بيانات مخصصة + +## المعاملات + +تقبل `RagTool` المعاملات التالية: + +- **summarize**: اختياري. ما إذا كان يتم تلخيص المحتوى المسترجع. القيمة الافتراضية `False`. +- **adapter**: اختياري. محول مخصص لقاعدة المعرفة. إذا لم يُقدَّم، سيُستخدم CrewAIRagAdapter. +- **config**: اختياري. إعداد نظام RAG الأساسي في CrewAI. يقبل TypedDict من نوع `RagToolConfig` مع مفاتيح اختيارية `embedding_model` (ProviderSpec) و`vectordb` (VectorDbConfig). جميع قيم الإعداد المقدمة برمجياً لها الأولوية على متغيرات البيئة. + +## إضافة المحتوى + +يمكنك إضافة محتوى إلى قاعدة المعرفة باستخدام طريقة `add`: + +```python Code +# Add a PDF file +rag_tool.add(data_type="file", path="path/to/your/document.pdf") + +# Add a web page +rag_tool.add(data_type="web_page", url="https://example.com") + +# Add a YouTube video +rag_tool.add(data_type="youtube_video", url="https://www.youtube.com/watch?v=VIDEO_ID") + +# Add a directory of files +rag_tool.add(data_type="directory", path="path/to/your/directory") +``` + +## مثال على التكامل مع الوكيل + +إليك كيفية دمج `RagTool` مع وكيل CrewAI: + +```python Code +from crewai import Agent +from crewai.project import agent +from crewai_tools import RagTool + +# Initialize the tool and add content +rag_tool = RagTool() +rag_tool.add(data_type="web_page", url="https://docs.crewai.com") +rag_tool.add(data_type="file", path="company_data.pdf") + +# Define an agent with the RagTool +@agent +def knowledge_expert(self) -> Agent: + return Agent( + config=self.agents_config["knowledge_expert"], + allow_delegation=False, + tools=[rag_tool] + ) +``` + +## إعداد متقدم + +يمكنك تخصيص سلوك `RagTool` من خلال تقديم قاموس إعداد: + +```python Code +from crewai_tools import RagTool +from crewai_tools.tools.rag import RagToolConfig, VectorDbConfig, ProviderSpec + +# Create a RAG tool with custom configuration + +vectordb: VectorDbConfig = { + "provider": "qdrant", + "config": { + "collection_name": "my-collection" + } +} + +embedding_model: ProviderSpec = { + "provider": "openai", + "config": { + "model_name": "text-embedding-3-small" + } +} + +config: RagToolConfig = { + "vectordb": vectordb, + "embedding_model": embedding_model +} + +rag_tool = RagTool(config=config, summarize=True) +``` + +## إعداد نموذج التضمين + +يقبل معامل `embedding_model` قاموس `crewai.rag.embeddings.types.ProviderSpec` بالبنية التالية: + +```python +{ + "provider": "provider-name", # Required + "config": { # Optional + # Provider-specific configuration + } +} +``` + +### المزودون المدعومون + + + + ```python main.py + from crewai.rag.embeddings.providers.openai.types import OpenAIProviderSpec + + embedding_model: OpenAIProviderSpec = { + "provider": "openai", + "config": { + "api_key": "your-api-key", + "model_name": "text-embedding-ada-002", + "dimensions": 1536, + "organization_id": "your-org-id", + "api_base": "https://api.openai.com/v1", + "api_version": "v1", + "default_headers": {"Custom-Header": "value"} + } + } + ``` + + **خيارات الإعداد:** + - `api_key` (str): مفتاح API لـ OpenAI + - `model_name` (str): النموذج المستخدم. القيمة الافتراضية: `text-embedding-ada-002`. الخيارات: `text-embedding-3-small`، `text-embedding-3-large`، `text-embedding-ada-002` + - `dimensions` (int): عدد أبعاد التضمين + - `organization_id` (str): معرّف منظمة OpenAI + - `api_base` (str): عنوان URL مخصص لقاعدة API + - `api_version` (str): إصدار API + - `default_headers` (dict): ترويسات مخصصة لطلبات API + + **متغيرات البيئة:** + - `OPENAI_API_KEY` أو `EMBEDDINGS_OPENAI_API_KEY`: `api_key` + - `OPENAI_ORGANIZATION_ID` أو `EMBEDDINGS_OPENAI_ORGANIZATION_ID`: `organization_id` + - `OPENAI_MODEL_NAME` أو `EMBEDDINGS_OPENAI_MODEL_NAME`: `model_name` + - `OPENAI_API_BASE` أو `EMBEDDINGS_OPENAI_API_BASE`: `api_base` + - `OPENAI_API_VERSION` أو `EMBEDDINGS_OPENAI_API_VERSION`: `api_version` + - `OPENAI_DIMENSIONS` أو `EMBEDDINGS_OPENAI_DIMENSIONS`: `dimensions` + + + + ```python main.py + from crewai.rag.embeddings.providers.cohere.types import CohereProviderSpec + + embedding_model: CohereProviderSpec = { + "provider": "cohere", + "config": { + "api_key": "your-api-key", + "model_name": "embed-english-v3.0" + } + } + ``` + + **خيارات الإعداد:** + - `api_key` (str): مفتاح API لـ Cohere + - `model_name` (str): النموذج المستخدم. القيمة الافتراضية: `large`. الخيارات: `embed-english-v3.0`، `embed-multilingual-v3.0`، `large`، `small` + + **متغيرات البيئة:** + - `COHERE_API_KEY` أو `EMBEDDINGS_COHERE_API_KEY`: `api_key` + - `EMBEDDINGS_COHERE_MODEL_NAME`: `model_name` + + + + ```python main.py + from crewai.rag.embeddings.providers.voyageai.types import VoyageAIProviderSpec + + embedding_model: VoyageAIProviderSpec = { + "provider": "voyageai", + "config": { + "api_key": "your-api-key", + "model": "voyage-3", + "input_type": "document", + "truncation": True, + "output_dtype": "float32", + "output_dimension": 1024, + "max_retries": 3, + "timeout": 60.0 + } + } + ``` + + **خيارات الإعداد:** + - `api_key` (str): مفتاح API لـ VoyageAI + - `model` (str): النموذج المستخدم. القيمة الافتراضية: `voyage-2`. الخيارات: `voyage-3`، `voyage-3-lite`، `voyage-code-3`، `voyage-large-2` + - `input_type` (str): نوع الإدخال. الخيارات: `document` (للتخزين)، `query` (للبحث) + - `truncation` (bool): ما إذا كان يتم اقتطاع المدخلات التي تتجاوز الحد الأقصى. القيمة الافتراضية: `True` + - `output_dtype` (str): نوع بيانات المخرجات + - `output_dimension` (int): بُعد تضمينات المخرجات + - `max_retries` (int): الحد الأقصى لمحاولات إعادة المحاولة. القيمة الافتراضية: `0` + - `timeout` (float): مهلة الطلب بالثواني + + **متغيرات البيئة:** + - `VOYAGEAI_API_KEY` أو `EMBEDDINGS_VOYAGEAI_API_KEY`: `api_key` + - `VOYAGEAI_MODEL` أو `EMBEDDINGS_VOYAGEAI_MODEL`: `model` + - `VOYAGEAI_INPUT_TYPE` أو `EMBEDDINGS_VOYAGEAI_INPUT_TYPE`: `input_type` + - `VOYAGEAI_TRUNCATION` أو `EMBEDDINGS_VOYAGEAI_TRUNCATION`: `truncation` + - `VOYAGEAI_OUTPUT_DTYPE` أو `EMBEDDINGS_VOYAGEAI_OUTPUT_DTYPE`: `output_dtype` + - `VOYAGEAI_OUTPUT_DIMENSION` أو `EMBEDDINGS_VOYAGEAI_OUTPUT_DIMENSION`: `output_dimension` + - `VOYAGEAI_MAX_RETRIES` أو `EMBEDDINGS_VOYAGEAI_MAX_RETRIES`: `max_retries` + - `VOYAGEAI_TIMEOUT` أو `EMBEDDINGS_VOYAGEAI_TIMEOUT`: `timeout` + + + + ```python main.py + from crewai.rag.embeddings.providers.ollama.types import OllamaProviderSpec + + embedding_model: OllamaProviderSpec = { + "provider": "ollama", + "config": { + "model_name": "llama2", + "url": "http://localhost:11434/api/embeddings" + } + } + ``` + + **خيارات الإعداد:** + - `model_name` (str): اسم نموذج Ollama (مثل `llama2`، `mistral`، `nomic-embed-text`) + - `url` (str): عنوان URL لنقطة نهاية API الخاصة بـ Ollama. القيمة الافتراضية: `http://localhost:11434/api/embeddings` + + **متغيرات البيئة:** + - `OLLAMA_MODEL` أو `EMBEDDINGS_OLLAMA_MODEL`: `model_name` + - `OLLAMA_URL` أو `EMBEDDINGS_OLLAMA_URL`: `url` + + + + ```python main.py + from crewai.rag.embeddings.providers.aws.types import BedrockProviderSpec + + embedding_model: BedrockProviderSpec = { + "provider": "amazon-bedrock", + "config": { + "model_name": "amazon.titan-embed-text-v2:0", + "session": boto3_session + } + } + ``` + + **خيارات الإعداد:** + - `model_name` (str): معرّف نموذج Bedrock. القيمة الافتراضية: `amazon.titan-embed-text-v1`. الخيارات: `amazon.titan-embed-text-v1`، `amazon.titan-embed-text-v2:0`، `cohere.embed-english-v3`، `cohere.embed-multilingual-v3` + - `session` (Any): كائن جلسة Boto3 لمصادقة AWS + + **متغيرات البيئة:** + - `AWS_ACCESS_KEY_ID`: مفتاح وصول AWS + - `AWS_SECRET_ACCESS_KEY`: مفتاح سري AWS + - `AWS_REGION`: منطقة AWS (مثل `us-east-1`) + + + + ```python main.py + from crewai.rag.embeddings.providers.microsoft.types import AzureProviderSpec + + embedding_model: AzureProviderSpec = { + "provider": "azure", + "config": { + "deployment_id": "your-deployment-id", + "api_key": "your-api-key", + "api_base": "https://your-resource.openai.azure.com", + "api_version": "2024-02-01", + "model_name": "text-embedding-ada-002", + "api_type": "azure" + } + } + ``` + + **خيارات الإعداد:** + - `deployment_id` (str): **مطلوب** - معرّف نشر Azure OpenAI + - `api_key` (str): مفتاح API لـ Azure OpenAI + - `api_base` (str): نقطة نهاية مورد Azure OpenAI + - `api_version` (str): إصدار API. مثال: `2024-02-01` + - `model_name` (str): اسم النموذج. القيمة الافتراضية: `text-embedding-ada-002` + - `api_type` (str): نوع API. القيمة الافتراضية: `azure` + - `dimensions` (int): أبعاد المخرجات + - `default_headers` (dict): ترويسات مخصصة + + **متغيرات البيئة:** + - `AZURE_OPENAI_API_KEY` أو `EMBEDDINGS_AZURE_API_KEY`: `api_key` + - `AZURE_OPENAI_ENDPOINT` أو `EMBEDDINGS_AZURE_API_BASE`: `api_base` + - `EMBEDDINGS_AZURE_DEPLOYMENT_ID`: `deployment_id` + - `EMBEDDINGS_AZURE_API_VERSION`: `api_version` + - `EMBEDDINGS_AZURE_MODEL_NAME`: `model_name` + - `EMBEDDINGS_AZURE_API_TYPE`: `api_type` + - `EMBEDDINGS_AZURE_DIMENSIONS`: `dimensions` + + + + ```python main.py + from crewai.rag.embeddings.providers.google.types import GenerativeAiProviderSpec + + embedding_model: GenerativeAiProviderSpec = { + "provider": "google-generativeai", + "config": { + "api_key": "your-api-key", + "model_name": "gemini-embedding-001", + "task_type": "RETRIEVAL_DOCUMENT" + } + } + ``` + + **خيارات الإعداد:** + - `api_key` (str): مفتاح API لـ Google AI + - `model_name` (str): اسم النموذج. القيمة الافتراضية: `gemini-embedding-001`. الخيارات: `gemini-embedding-001`، `text-embedding-005`، `text-multilingual-embedding-002` + - `task_type` (str): نوع المهمة للتضمينات. القيمة الافتراضية: `RETRIEVAL_DOCUMENT`. الخيارات: `RETRIEVAL_DOCUMENT`، `RETRIEVAL_QUERY` + + **متغيرات البيئة:** + - `GOOGLE_API_KEY` أو `GEMINI_API_KEY` أو `EMBEDDINGS_GOOGLE_API_KEY`: `api_key` + - `EMBEDDINGS_GOOGLE_GENERATIVE_AI_MODEL_NAME`: `model_name` + - `EMBEDDINGS_GOOGLE_GENERATIVE_AI_TASK_TYPE`: `task_type` + + + + ```python main.py + from crewai.rag.embeddings.providers.google.types import VertexAIProviderSpec + + embedding_model: VertexAIProviderSpec = { + "provider": "google-vertex", + "config": { + "model_name": "text-embedding-004", + "project_id": "your-project-id", + "region": "us-central1", + "api_key": "your-api-key" + } + } + ``` + + **خيارات الإعداد:** + - `model_name` (str): اسم النموذج. القيمة الافتراضية: `textembedding-gecko`. الخيارات: `text-embedding-004`، `textembedding-gecko`، `textembedding-gecko-multilingual` + - `project_id` (str): معرّف مشروع Google Cloud. القيمة الافتراضية: `cloud-large-language-models` + - `region` (str): منطقة Google Cloud. القيمة الافتراضية: `us-central1` + - `api_key` (str): مفتاح API للمصادقة + + **متغيرات البيئة:** + - `GOOGLE_APPLICATION_CREDENTIALS`: مسار ملف JSON لحساب الخدمة + - `GOOGLE_CLOUD_PROJECT` أو `EMBEDDINGS_GOOGLE_VERTEX_PROJECT_ID`: `project_id` + - `EMBEDDINGS_GOOGLE_VERTEX_MODEL_NAME`: `model_name` + - `EMBEDDINGS_GOOGLE_VERTEX_REGION`: `region` + - `EMBEDDINGS_GOOGLE_VERTEX_API_KEY`: `api_key` + + + + ```python main.py + from crewai.rag.embeddings.providers.jina.types import JinaProviderSpec + + embedding_model: JinaProviderSpec = { + "provider": "jina", + "config": { + "api_key": "your-api-key", + "model_name": "jina-embeddings-v3" + } + } + ``` + + **خيارات الإعداد:** + - `api_key` (str): مفتاح API لـ Jina AI + - `model_name` (str): اسم النموذج. القيمة الافتراضية: `jina-embeddings-v2-base-en`. الخيارات: `jina-embeddings-v3`، `jina-embeddings-v2-base-en`، `jina-embeddings-v2-small-en` + + **متغيرات البيئة:** + - `JINA_API_KEY` أو `EMBEDDINGS_JINA_API_KEY`: `api_key` + - `EMBEDDINGS_JINA_MODEL_NAME`: `model_name` + + + + ```python main.py + from crewai.rag.embeddings.providers.huggingface.types import HuggingFaceProviderSpec + + embedding_model: HuggingFaceProviderSpec = { + "provider": "huggingface", + "config": { + "url": "https://api-inference.huggingface.co/models/sentence-transformers/all-MiniLM-L6-v2" + } + } + ``` + + **خيارات الإعداد:** + - `url` (str): عنوان URL الكامل لنقطة نهاية API الاستدلالي لـ HuggingFace + + **متغيرات البيئة:** + - `HUGGINGFACE_URL` أو `EMBEDDINGS_HUGGINGFACE_URL`: `url` + + + + ```python main.py + from crewai.rag.embeddings.providers.instructor.types import InstructorProviderSpec + + embedding_model: InstructorProviderSpec = { + "provider": "instructor", + "config": { + "model_name": "hkunlp/instructor-xl", + "device": "cuda", + "instruction": "Represent the document" + } + } + ``` + + **خيارات الإعداد:** + - `model_name` (str): معرّف نموذج HuggingFace. القيمة الافتراضية: `hkunlp/instructor-base`. الخيارات: `hkunlp/instructor-xl`، `hkunlp/instructor-large`، `hkunlp/instructor-base` + - `device` (str): الجهاز للتشغيل. القيمة الافتراضية: `cpu`. الخيارات: `cpu`، `cuda`، `mps` + - `instruction` (str): بادئة التعليمات للتضمينات + + **متغيرات البيئة:** + - `EMBEDDINGS_INSTRUCTOR_MODEL_NAME`: `model_name` + - `EMBEDDINGS_INSTRUCTOR_DEVICE`: `device` + - `EMBEDDINGS_INSTRUCTOR_INSTRUCTION`: `instruction` + + + + ```python main.py + from crewai.rag.embeddings.providers.sentence_transformer.types import SentenceTransformerProviderSpec + + embedding_model: SentenceTransformerProviderSpec = { + "provider": "sentence-transformer", + "config": { + "model_name": "all-mpnet-base-v2", + "device": "cuda", + "normalize_embeddings": True + } + } + ``` + + **خيارات الإعداد:** + - `model_name` (str): اسم نموذج Sentence Transformers. القيمة الافتراضية: `all-MiniLM-L6-v2`. الخيارات: `all-mpnet-base-v2`، `all-MiniLM-L6-v2`، `paraphrase-multilingual-MiniLM-L12-v2` + - `device` (str): الجهاز للتشغيل. القيمة الافتراضية: `cpu`. الخيارات: `cpu`، `cuda`، `mps` + - `normalize_embeddings` (bool): ما إذا كان يتم تطبيع التضمينات. القيمة الافتراضية: `False` + + **متغيرات البيئة:** + - `EMBEDDINGS_SENTENCE_TRANSFORMER_MODEL_NAME`: `model_name` + - `EMBEDDINGS_SENTENCE_TRANSFORMER_DEVICE`: `device` + - `EMBEDDINGS_SENTENCE_TRANSFORMER_NORMALIZE_EMBEDDINGS`: `normalize_embeddings` + + + + ```python main.py + from crewai.rag.embeddings.providers.onnx.types import ONNXProviderSpec + + embedding_model: ONNXProviderSpec = { + "provider": "onnx", + "config": { + "preferred_providers": ["CUDAExecutionProvider", "CPUExecutionProvider"] + } + } + ``` + + **خيارات الإعداد:** + - `preferred_providers` (list[str]): قائمة مزودي تنفيذ ONNX حسب ترتيب الأفضلية + + **متغيرات البيئة:** + - `EMBEDDINGS_ONNX_PREFERRED_PROVIDERS`: `preferred_providers` (قائمة مفصولة بفواصل) + + + + ```python main.py + from crewai.rag.embeddings.providers.openclip.types import OpenCLIPProviderSpec + + embedding_model: OpenCLIPProviderSpec = { + "provider": "openclip", + "config": { + "model_name": "ViT-B-32", + "checkpoint": "laion2b_s34b_b79k", + "device": "cuda" + } + } + ``` + + **خيارات الإعداد:** + - `model_name` (str): بنية نموذج OpenCLIP. القيمة الافتراضية: `ViT-B-32`. الخيارات: `ViT-B-32`، `ViT-B-16`، `ViT-L-14` + - `checkpoint` (str): اسم نقطة التحقق المُدرّبة مسبقاً. القيمة الافتراضية: `laion2b_s34b_b79k`. الخيارات: `laion2b_s34b_b79k`، `laion400m_e32`، `openai` + - `device` (str): الجهاز للتشغيل. القيمة الافتراضية: `cpu`. الخيارات: `cpu`، `cuda` + + **متغيرات البيئة:** + - `EMBEDDINGS_OPENCLIP_MODEL_NAME`: `model_name` + - `EMBEDDINGS_OPENCLIP_CHECKPOINT`: `checkpoint` + - `EMBEDDINGS_OPENCLIP_DEVICE`: `device` + + + + ```python main.py + from crewai.rag.embeddings.providers.text2vec.types import Text2VecProviderSpec + + embedding_model: Text2VecProviderSpec = { + "provider": "text2vec", + "config": { + "model_name": "shibing624/text2vec-base-multilingual" + } + } + ``` + + **خيارات الإعداد:** + - `model_name` (str): اسم نموذج Text2Vec من HuggingFace. القيمة الافتراضية: `shibing624/text2vec-base-chinese`. الخيارات: `shibing624/text2vec-base-multilingual`، `shibing624/text2vec-base-chinese` + + **متغيرات البيئة:** + - `EMBEDDINGS_TEXT2VEC_MODEL_NAME`: `model_name` + + + + ```python main.py + from crewai.rag.embeddings.providers.roboflow.types import RoboflowProviderSpec + + embedding_model: RoboflowProviderSpec = { + "provider": "roboflow", + "config": { + "api_key": "your-api-key", + "api_url": "https://infer.roboflow.com" + } + } + ``` + + **خيارات الإعداد:** + - `api_key` (str): مفتاح API لـ Roboflow. القيمة الافتراضية: `""` (سلسلة فارغة) + - `api_url` (str): عنوان URL لـ API الاستدلالي لـ Roboflow. القيمة الافتراضية: `https://infer.roboflow.com` + + **متغيرات البيئة:** + - `ROBOFLOW_API_KEY` أو `EMBEDDINGS_ROBOFLOW_API_KEY`: `api_key` + - `ROBOFLOW_API_URL` أو `EMBEDDINGS_ROBOFLOW_API_URL`: `api_url` + + + + ```python main.py + from crewai.rag.embeddings.providers.ibm.types import WatsonXProviderSpec + + embedding_model: WatsonXProviderSpec = { + "provider": "watsonx", + "config": { + "model_id": "ibm/slate-125m-english-rtrvr", + "url": "https://us-south.ml.cloud.ibm.com", + "api_key": "your-api-key", + "project_id": "your-project-id", + "batch_size": 100, + "concurrency_limit": 10, + "persistent_connection": True + } + } + ``` + + **خيارات الإعداد:** + - `model_id` (str): معرّف نموذج WatsonX + - `url` (str): نقطة نهاية API لـ WatsonX + - `api_key` (str): مفتاح API لـ IBM Cloud + - `project_id` (str): معرّف مشروع WatsonX + - `space_id` (str): معرّف مساحة WatsonX (بديل لـ project_id) + - `batch_size` (int): حجم الدفعة للتضمينات. القيمة الافتراضية: `100` + - `concurrency_limit` (int): الحد الأقصى للطلبات المتزامنة. القيمة الافتراضية: `10` + - `persistent_connection` (bool): استخدام اتصالات مستمرة. القيمة الافتراضية: `True` + - بالإضافة إلى أكثر من 20 خيار مصادقة وإعداد إضافي + + **متغيرات البيئة:** + - `WATSONX_API_KEY` أو `EMBEDDINGS_WATSONX_API_KEY`: `api_key` + - `WATSONX_URL` أو `EMBEDDINGS_WATSONX_URL`: `url` + - `WATSONX_PROJECT_ID` أو `EMBEDDINGS_WATSONX_PROJECT_ID`: `project_id` + - `EMBEDDINGS_WATSONX_MODEL_ID`: `model_id` + - `EMBEDDINGS_WATSONX_SPACE_ID`: `space_id` + - `EMBEDDINGS_WATSONX_BATCH_SIZE`: `batch_size` + - `EMBEDDINGS_WATSONX_CONCURRENCY_LIMIT`: `concurrency_limit` + - `EMBEDDINGS_WATSONX_PERSISTENT_CONNECTION`: `persistent_connection` + + + + ```python main.py + from crewai.rag.core.base_embeddings_callable import EmbeddingFunction + from crewai.rag.embeddings.providers.custom.types import CustomProviderSpec + + class MyEmbeddingFunction(EmbeddingFunction): + def __call__(self, input): + # Your custom embedding logic + return embeddings + + embedding_model: CustomProviderSpec = { + "provider": "custom", + "config": { + "embedding_callable": MyEmbeddingFunction + } + } + ``` + + **خيارات الإعداد:** + - `embedding_callable` (type[EmbeddingFunction]): فئة دالة تضمين مخصصة + + **ملاحظة:** يجب أن تنفّذ دوال التضمين المخصصة بروتوكول `EmbeddingFunction` المحدد في `crewai.rag.core.base_embeddings_callable`. يجب أن تقبل طريقة `__call__` بيانات الإدخال وتعيد التضمينات كقائمة من مصفوفات numpy (أو تنسيق متوافق سيتم تطبيعه). يتم تطبيع التضمينات المُعادة والتحقق منها تلقائياً. + + + +### ملاحظات +- جميع حقول الإعداد اختيارية ما لم يُذكر أنها **مطلوبة** +- يمكن عادة تقديم مفاتيح API عبر متغيرات البيئة بدلاً من الإعداد +- تُعرض القيم الافتراضية حيثما ينطبق ذلك + + +## الخلاصة +توفر `RagTool` طريقة قوية لإنشاء واستعلام قواعد المعرفة من مصادر بيانات متنوعة. من خلال الاستفادة من التوليد المعزز بالاسترجاع، تمكّن الوكلاء من الوصول إلى المعلومات ذات الصلة واسترجاعها بكفاءة، مما يعزز قدرتهم على تقديم استجابات دقيقة ومناسبة للسياق. diff --git a/docs/ar/tools/ai-ml/visiontool.mdx b/docs/ar/tools/ai-ml/visiontool.mdx new file mode 100644 index 000000000..ecd09a6a3 --- /dev/null +++ b/docs/ar/tools/ai-ml/visiontool.mdx @@ -0,0 +1,50 @@ +--- +title: أداة الرؤية +description: أداة `VisionTool` مصممة لاستخراج النص من الصور. +icon: eye +mode: "wide" +--- + +# `VisionTool` + +## الوصف + +تُستخدم هذه الأداة لاستخراج النص من الصور. عند تمريرها إلى الوكيل، ستستخرج النص من الصورة ثم تستخدمه لتوليد استجابة أو تقرير أو أي مخرج آخر. +يجب تمرير عنوان URL أو مسار الصورة إلى الوكيل. + +## التثبيت + +ثبّت حزمة crewai_tools + +```shell +pip install 'crewai[tools]' +``` + +## الاستخدام + +لاستخدام VisionTool، يجب تعيين مفتاح API الخاص بـ OpenAI في متغير البيئة `OPENAI_API_KEY`. + +```python Code +from crewai_tools import VisionTool + +vision_tool = VisionTool() + +@agent +def researcher(self) -> Agent: + ''' + This agent uses the VisionTool to extract text from images. + ''' + return Agent( + config=self.agents_config["researcher"], + allow_delegation=False, + tools=[vision_tool] + ) +``` + +## المعاملات + +تتطلب VisionTool المعاملات التالية: + +| المعامل | النوع | الوصف | +| :----------------- | :------- | :------------------------------------------------------------------------------- | +| **image_path_url** | `string` | **إلزامي**. مسار ملف الصورة المراد استخراج النص منها. | diff --git a/docs/ar/tools/automation/apifyactorstool.mdx b/docs/ar/tools/automation/apifyactorstool.mdx new file mode 100644 index 000000000..77c8c38c4 --- /dev/null +++ b/docs/ar/tools/automation/apifyactorstool.mdx @@ -0,0 +1,99 @@ +--- +title: Apify Actors +description: "تتيح لك `ApifyActorsTool` استدعاء Apify Actors لتوفير إمكانيات تجريف الويب والزحف واستخراج البيانات وأتمتة الويب لسير عمل CrewAI." +icon: "); -webkit-mask-image: url('https://upload.wikimedia.org/wikipedia/commons/a/ae/Apify.svg');/*" +mode: "wide" +--- + +# `ApifyActorsTool` + +دمج [Apify Actors](https://apify.com/actors) في سير عمل CrewAI الخاص بك. + +## الوصف + +تربط `ApifyActorsTool` بين [Apify Actors](https://apify.com/actors)، وهي برامج سحابية لتجريف الويب والأتمتة، وسير عمل CrewAI الخاص بك. +استخدم أياً من أكثر من 4,000 Actor على [متجر Apify](https://apify.com/store) لحالات استخدام مثل استخراج البيانات من وسائل التواصل الاجتماعي ومحركات البحث والخرائط الإلكترونية ومواقع التجارة الإلكترونية وبوابات السفر أو المواقع العامة. + +للتفاصيل، راجع [تكامل Apify CrewAI](https://docs.apify.com/platform/integrations/crewai) في وثائق Apify. + +## خطوات البدء + + + + ثبّت `crewai[tools]` و`langchain-apify` باستخدام pip: `pip install 'crewai[tools]' langchain-apify`. + + + سجّل في [وحدة تحكم Apify](https://console.apify.com/) واحصل على [رمز API الخاص بك](https://console.apify.com/settings/integrations). + + + عيّن رمز API لـ Apify كمتغير بيئة `APIFY_API_TOKEN` لتمكين وظائف الأداة. + + + +## مثال على الاستخدام + +استخدم `ApifyActorsTool` يدوياً لتشغيل [RAG Web Browser Actor](https://apify.com/apify/rag-web-browser) لإجراء بحث ويب: + +```python +from crewai_tools import ApifyActorsTool + +# Initialize the tool with an Apify Actor +tool = ApifyActorsTool(actor_name="apify/rag-web-browser") + +# Run the tool with input parameters +results = tool.run(run_input={"query": "What is CrewAI?", "maxResults": 5}) + +# Process the results +for result in results: + print(f"URL: {result['metadata']['url']}") + print(f"Content: {result.get('markdown', 'N/A')[:100]}...") +``` + +### المخرجات المتوقعة + +إليك المخرجات من تشغيل الكود أعلاه: + +```text +URL: https://www.example.com/crewai-intro +Content: CrewAI is a framework for building AI-powered workflows... +URL: https://docs.crewai.com/ +Content: Official documentation for CrewAI... +``` + +تقوم `ApifyActorsTool` تلقائياً بجلب تعريف Actor ومخطط الإدخال من Apify باستخدام `actor_name` المقدم ثم تبني وصف الأداة ومخطط المعاملات. هذا يعني أنك تحتاج فقط إلى تحديد `actor_name` صالح، والأداة تتعامل مع الباقي عند استخدامها مع الوكلاء - دون الحاجة لتحديد `run_input`. إليك كيفية عمل ذلك: + +```python +from crewai import Agent +from crewai_tools import ApifyActorsTool + +rag_browser = ApifyActorsTool(actor_name="apify/rag-web-browser") + +agent = Agent( + role="Research Analyst", + goal="Find and summarize information about specific topics", + backstory="You are an experienced researcher with attention to detail", + tools=[rag_browser], +) +``` + +يمكنك تشغيل Actors أخرى من [متجر Apify](https://apify.com/store) ببساطة عن طريق تغيير `actor_name` وعند الاستخدام اليدوي، ضبط `run_input` بناءً على مخطط إدخال Actor. + +لمثال على الاستخدام مع الوكلاء، راجع [قالب CrewAI Actor](https://apify.com/templates/python-crewai). + +## الإعداد + +تتطلب `ApifyActorsTool` المدخلات التالية للعمل: + +- **`actor_name`** + معرّف Apify Actor المراد تشغيله، مثل `"apify/rag-web-browser"`. تصفح جميع Actors على [متجر Apify](https://apify.com/store). +- **`run_input`** + قاموس من معاملات الإدخال لـ Actor عند تشغيل الأداة يدوياً. + - على سبيل المثال، لـ Actor `apify/rag-web-browser`: `{"query": "search term", "maxResults": 5}` + - راجع [مخطط إدخال](https://apify.com/apify/rag-web-browser/input-schema) Actor لقائمة معاملات الإدخال. + +## الموارد + +- **[Apify](https://apify.com/)**: استكشف منصة Apify. +- **[كيفية بناء وكيل ذكاء اصطناعي على Apify](https://blog.apify.com/how-to-build-an-ai-agent/)** - دليل شامل خطوة بخطوة لإنشاء ونشر وتسويق وكلاء الذكاء الاصطناعي على منصة Apify. +- **[RAG Web Browser Actor](https://apify.com/apify/rag-web-browser)**: Actor شائع لبحث الويب لنماذج LLM. +- **[دليل تكامل CrewAI](https://docs.apify.com/platform/integrations/crewai)**: اتبع الدليل الرسمي لتكامل Apify وCrewAI. diff --git a/docs/ar/tools/automation/composiotool.mdx b/docs/ar/tools/automation/composiotool.mdx new file mode 100644 index 000000000..78e81b556 --- /dev/null +++ b/docs/ar/tools/automation/composiotool.mdx @@ -0,0 +1,88 @@ +--- +title: أداة Composio +description: يوفر Composio أكثر من 250 أداة جاهزة للإنتاج لوكلاء الذكاء الاصطناعي مع إدارة مصادقة مرنة. +icon: gear-code +mode: "wide" +--- + +# `ComposioToolSet` + +## الوصف +Composio هو منصة تكامل تتيح لك ربط وكلاء الذكاء الاصطناعي بأكثر من 250 أداة. تشمل الميزات الرئيسية: + +- **مصادقة على مستوى المؤسسة**: دعم مدمج لـ OAuth ومفاتيح API وJWT مع تحديث الرموز تلقائياً +- **مراقبة كاملة**: سجلات استخدام أدوات تفصيلية وطوابع تنفيذ زمنية والمزيد + +## التثبيت + +لدمج أدوات Composio في مشروعك، اتبع التعليمات أدناه: + +```shell +pip install composio composio-crewai +pip install crewai +``` + +بعد اكتمال التثبيت، عيّن مفتاح API الخاص بك لـ Composio كـ `COMPOSIO_API_KEY`. احصل على مفتاح API من [هنا](https://platform.composio.dev) + +## مثال + +يوضح المثال التالي كيفية تهيئة الأداة وتنفيذ إجراء على GitHub: + +1. تهيئة Composio مع مزود CrewAI + +```python Code +from composio_crewai import ComposioProvider +from composio import Composio +from crewai import Agent, Task, Crew + +composio = Composio(provider=ComposioProvider()) +``` + +2. إنشاء جلسة Composio جديدة واسترجاع الأدوات + +```python +session = composio.create( + user_id="your-user-id", + toolkits=["gmail", "github"] # optional, default is all toolkits +) +tools = session.tools() +``` +اقرأ المزيد حول الجلسات وإدارة المستخدمين [هنا](https://docs.composio.dev/docs/configuring-sessions) + + +3. مصادقة المستخدمين يدوياً + +يقوم Composio بمصادقة المستخدمين تلقائياً أثناء جلسة دردشة الوكيل. ومع ذلك، يمكنك أيضاً مصادقة المستخدم يدوياً عبر استدعاء طريقة `authorize`. +```python Code +connection_request = session.authorize("github") +print(f"Open this URL to authenticate: {connection_request.redirect_url}") +``` + +4. تعريف الوكيل + +```python Code +crewai_agent = Agent( + role="GitHub Agent", + goal="You take action on GitHub using GitHub APIs", + backstory="You are AI agent that is responsible for taking actions on GitHub on behalf of users using GitHub APIs", + verbose=True, + tools=tools, + llm= # pass an llm +) +``` + +5. تنفيذ المهمة + +```python Code +task = Task( + description="Star a repo composiohq/composio on GitHub", + agent=crewai_agent, + expected_output="Status of the operation", +) + +crew = Crew(agents=[crewai_agent], tasks=[task]) + +crew.kickoff() +``` + +* يمكن العثور على قائمة أكثر تفصيلاً من الأدوات [هنا](https://docs.composio.dev/toolkits) diff --git a/docs/ar/tools/automation/multiontool.mdx b/docs/ar/tools/automation/multiontool.mdx new file mode 100644 index 000000000..2d767a1f8 --- /dev/null +++ b/docs/ar/tools/automation/multiontool.mdx @@ -0,0 +1,127 @@ +--- +title: أداة MultiOn +description: تمكّن `MultiOnTool` وكلاء CrewAI من التنقل والتفاعل مع الويب من خلال تعليمات اللغة الطبيعية. +icon: globe +mode: "wide" +--- + +## نظرة عامة + +صُممت `MultiOnTool` لتغليف قدرات تصفح الويب الخاصة بـ [MultiOn](https://docs.multion.ai/welcome)، مما يمكّن وكلاء CrewAI من التحكم في متصفحات الويب باستخدام تعليمات اللغة الطبيعية. تسهّل هذه الأداة تصفح الويب بسلاسة، مما يجعلها أصلاً أساسياً للمشاريع التي تتطلب تفاعلاً ديناميكياً مع بيانات الويب وأتمتة المهام المستندة إلى الويب. + +## التثبيت + +لاستخدام هذه الأداة، تحتاج إلى تثبيت حزمة MultiOn: + +```shell +uv add multion +``` + +ستحتاج أيضاً إلى تثبيت إضافة متصفح MultiOn وتفعيل استخدام API. + +## خطوات البدء + +لاستخدام `MultiOnTool` بفعالية، اتبع الخطوات التالية: + +1. **تثبيت CrewAI**: تأكد من تثبيت حزمة `crewai[tools]` في بيئة Python. +2. **تثبيت واستخدام MultiOn**: اتبع [وثائق MultiOn](https://docs.multion.ai/learn/browser-extension) لتثبيت إضافة متصفح MultiOn. +3. **تفعيل استخدام API**: انقر على إضافة MultiOn في مجلد الإضافات في متصفحك (وليس أيقونة MultiOn العائمة على صفحة الويب) لفتح إعدادات الإضافة. انقر على زر تفعيل API لتمكينه. + +## مثال + +يوضح المثال التالي كيفية تهيئة الأداة وتنفيذ مهمة تصفح ويب: + +```python Code +from crewai import Agent, Task, Crew +from crewai_tools import MultiOnTool + +# Initialize the tool +multion_tool = MultiOnTool(api_key="YOUR_MULTION_API_KEY", local=False) + +# Define an agent that uses the tool +browser_agent = Agent( + role="Browser Agent", + goal="Control web browsers using natural language", + backstory="An expert browsing agent.", + tools=[multion_tool], + verbose=True, +) + +# Example task to search and summarize news +browse_task = Task( + description="Summarize the top 3 trending AI News headlines", + expected_output="A summary of the top 3 trending AI News headlines", + agent=browser_agent, +) + +# Create and run the crew +crew = Crew(agents=[browser_agent], tasks=[browse_task]) +result = crew.kickoff() +``` + +## المعاملات + +تقبل `MultiOnTool` المعاملات التالية أثناء التهيئة: + +- **api_key**: اختياري. يحدد مفتاح API لـ MultiOn. إذا لم يُقدَّم، سيبحث عن متغير البيئة `MULTION_API_KEY`. +- **local**: اختياري. عيّنه إلى `True` لتشغيل الوكيل محلياً على متصفحك. تأكد من تثبيت إضافة متصفح MultiOn وتفعيل API. القيمة الافتراضية `False`. +- **max_steps**: اختياري. يحدد الحد الأقصى لعدد الخطوات التي يمكن لوكيل MultiOn اتخاذها لأمر ما. القيمة الافتراضية `3`. + +## الاستخدام + +عند استخدام `MultiOnTool`، سيقدم الوكيل تعليمات بلغة طبيعية تترجمها الأداة إلى إجراءات تصفح ويب. تعيد الأداة نتائج جلسة التصفح مع الحالة. + +```python Code +# Example of using the tool with an agent +browser_agent = Agent( + role="Web Browser Agent", + goal="Search for and summarize information from the web", + backstory="An expert at finding and extracting information from websites.", + tools=[multion_tool], + verbose=True, +) + +# Create a task for the agent +search_task = Task( + description="Search for the latest AI news on TechCrunch and summarize the top 3 headlines", + expected_output="A summary of the top 3 AI news headlines from TechCrunch", + agent=browser_agent, +) + +# Run the task +crew = Crew(agents=[browser_agent], tasks=[search_task]) +result = crew.kickoff() +``` + +إذا كانت الحالة المُعادة هي `CONTINUE`، يجب توجيه الوكيل لإعادة إصدار نفس التعليمات لمتابعة التنفيذ. + +## تفاصيل التنفيذ + +`MultiOnTool` منفذة كفئة فرعية من `BaseTool` في CrewAI. تغلف عميل MultiOn لتوفير قدرات تصفح الويب: + +```python Code +class MultiOnTool(BaseTool): + """Tool to wrap MultiOn Browse Capabilities.""" + + name: str = "Multion Browse Tool" + description: str = """Multion gives the ability for LLMs to control web browsers using natural language instructions. + If the status is 'CONTINUE', reissue the same instruction to continue execution + """ + + # Implementation details... + + def _run(self, cmd: str, *args: Any, **kwargs: Any) -> str: + """ + Run the Multion client with the given command. + + Args: + cmd (str): The detailed and specific natural language instruction for web browsing + *args (Any): Additional arguments to pass to the Multion client + **kwargs (Any): Additional keyword arguments to pass to the Multion client + """ + # Implementation details... +``` + +## الخلاصة + +توفر `MultiOnTool` طريقة قوية لدمج قدرات تصفح الويب في وكلاء CrewAI. من خلال تمكين الوكلاء من التفاعل مع المواقع عبر تعليمات اللغة الطبيعية، تفتح مجموعة واسعة من الإمكانيات للمهام المستندة إلى الويب، من جمع البيانات والبحث إلى التفاعلات الآلية مع خدمات الويب. diff --git a/docs/ar/tools/automation/overview.mdx b/docs/ar/tools/automation/overview.mdx new file mode 100644 index 000000000..0d33d5f4e --- /dev/null +++ b/docs/ar/tools/automation/overview.mdx @@ -0,0 +1,60 @@ +--- +title: "نظرة عامة" +description: "أتمتة سير العمل والتكامل مع المنصات والخدمات الخارجية" +icon: "face-smile" +mode: "wide" +--- + +تمكّن هذه الأدوات وكلاءك من أتمتة سير العمل والتكامل مع المنصات الخارجية والاتصال بخدمات الطرف الثالث المتنوعة لتعزيز الوظائف. + +## **الأدوات المتاحة** + + + + تشغيل Apify Actors لمهام تجريف الويب والأتمتة. + + + + التكامل مع مئات التطبيقات والخدمات من خلال Composio. + + + + أتمتة تفاعلات المتصفح وسير العمل المستند إلى الويب. + + + + عرض إجراءات Zapier كأدوات CrewAI للأتمتة عبر آلاف التطبيقات. + + + +## **حالات الاستخدام الشائعة** + +- **أتمتة سير العمل**: أتمتة المهام والعمليات المتكررة +- **تكامل API**: الاتصال بواجهات برمجة التطبيقات والخدمات الخارجية +- **مزامنة البيانات**: مزامنة البيانات بين منصات مختلفة +- **تنسيق العمليات**: تنسيق سير العمل المعقد متعدد الخطوات +- **خدمات الطرف الثالث**: الاستفادة من الأدوات والمنصات الخارجية + +```python +from crewai_tools import ApifyActorTool, ComposioTool, MultiOnTool + +# Create automation tools +apify_automation = ApifyActorTool() +platform_integration = ComposioTool() +browser_automation = MultiOnTool() + +# Add to your agent +agent = Agent( + role="Automation Specialist", + tools=[apify_automation, platform_integration, browser_automation], + goal="Automate workflows and integrate systems" +) +``` + +## **فوائد التكامل** + +- **الكفاءة**: تقليل العمل اليدوي من خلال الأتمتة +- **قابلية التوسع**: التعامل مع أعباء العمل المتزايدة تلقائياً +- **الموثوقية**: تنفيذ متسق لسير العمل +- **الاتصال**: ربط الأنظمة والمنصات المختلفة +- **الإنتاجية**: التركيز على المهام ذات القيمة العالية بينما تتولى الأتمتة العمل الروتيني diff --git a/docs/ar/tools/automation/zapieractionstool.mdx b/docs/ar/tools/automation/zapieractionstool.mdx new file mode 100644 index 000000000..a6e6d0774 --- /dev/null +++ b/docs/ar/tools/automation/zapieractionstool.mdx @@ -0,0 +1,59 @@ +--- +title: أداة إجراءات Zapier +description: يعرض `ZapierActionsAdapter` إجراءات Zapier كأدوات CrewAI للأتمتة. +icon: bolt +mode: "wide" +--- + +# `ZapierActionsAdapter` + +## الوصف + +استخدم محول Zapier لسرد واستدعاء إجراءات Zapier كأدوات CrewAI. يمكّن هذا الوكلاء من تشغيل عمليات الأتمتة عبر آلاف التطبيقات. + +## التثبيت + +هذا المحول مضمّن مع `crewai-tools`. لا يلزم تثبيت إضافي. + +## متغيرات البيئة + +- `ZAPIER_API_KEY` (مطلوب): مفتاح API لـ Zapier. احصل على واحد من لوحة تحكم Zapier Actions على https://actions.zapier.com/ (أنشئ حساباً، ثم ولّد مفتاح API). يمكنك أيضاً تمرير `zapier_api_key` مباشرة عند إنشاء المحول. + +## مثال + +```python Code +from crewai import Agent, Task, Crew +from crewai_tools.adapters.zapier_adapter import ZapierActionsAdapter + +adapter = ZapierActionsAdapter(api_key="your_zapier_api_key") +tools = adapter.tools() + +agent = Agent( + role="Automator", + goal="Execute Zapier actions", + backstory="Automation specialist", + tools=tools, + verbose=True, +) + +task = Task( + description="Create a new Google Sheet and add a row using Zapier actions", + expected_output="Confirmation with created resource IDs", + agent=agent, +) + +crew = Crew(agents=[agent], tasks=[task]) +result = crew.kickoff() +``` + +## ملاحظات وحدود + +- يسرد المحول الإجراءات المتاحة لمفتاحك وينشئ أغلفة `BaseTool` ديناميكياً. +- تعامل مع الحقول المطلوبة الخاصة بالإجراء في تعليمات المهمة أو استدعاء الأداة. +- تعتمد حدود المعدل على خطة Zapier الخاصة بك؛ راجع وثائق Zapier Actions. + +## ملاحظات + +- يجلب المحول الإجراءات المتاحة وينشئ أغلفة `BaseTool` ديناميكياً. + + diff --git a/docs/ar/tools/cloud-storage/bedrockkbretriever.mdx b/docs/ar/tools/cloud-storage/bedrockkbretriever.mdx new file mode 100644 index 000000000..d46a7a644 --- /dev/null +++ b/docs/ar/tools/cloud-storage/bedrockkbretriever.mdx @@ -0,0 +1,166 @@ +--- +title: 'مسترجع قاعدة معرفة Bedrock' +description: 'استرجاع المعلومات من قواعد معرفة Amazon Bedrock باستخدام استعلامات اللغة الطبيعية' +icon: aws +mode: "wide" +--- + +# `BedrockKBRetrieverTool` + +تمكّن `BedrockKBRetrieverTool` وكلاء CrewAI من استرجاع المعلومات من قواعد معرفة Amazon Bedrock باستخدام استعلامات اللغة الطبيعية. + +## التثبيت + +```bash +uv pip install 'crewai[tools]' +``` + +## المتطلبات + +- بيانات اعتماد AWS مُعدّة (إما من خلال متغيرات البيئة أو AWS CLI) +- حزمتا `boto3` و`python-dotenv` +- الوصول إلى قاعدة معرفة Amazon Bedrock + +## الاستخدام + +إليك كيفية استخدام الأداة مع وكيل CrewAI: + +```python {2, 4-17} +from crewai import Agent, Task, Crew +from crewai_tools.aws.bedrock.knowledge_base.retriever_tool import BedrockKBRetrieverTool + +# Initialize the tool +kb_tool = BedrockKBRetrieverTool( + knowledge_base_id="your-kb-id", + number_of_results=5 +) + +# Create a CrewAI agent that uses the tool +researcher = Agent( + role='Knowledge Base Researcher', + goal='Find information about company policies', + backstory='I am a researcher specialized in retrieving and analyzing company documentation.', + tools=[kb_tool], + verbose=True +) + +# Create a task for the agent +research_task = Task( + description="Find our company's remote work policy and summarize the key points.", + agent=researcher +) + +# Create a crew with the agent +crew = Crew( + agents=[researcher], + tasks=[research_task], + verbose=2 +) + +# Run the crew +result = crew.kickoff() +print(result) +``` + +## معاملات الأداة + +| المعامل | النوع | مطلوب | القيمة الافتراضية | الوصف | +|:---------|:-----|:---------|:---------|:-------------| +| **knowledge_base_id** | `str` | نعم | None | المعرّف الفريد لقاعدة المعرفة (0-10 أحرف أبجدية رقمية) | +| **number_of_results** | `int` | لا | 5 | الحد الأقصى لعدد النتائج المُعادة | +| **retrieval_configuration** | `dict` | لا | None | إعدادات مخصصة لاستعلام قاعدة المعرفة | +| **guardrail_configuration** | `dict` | لا | None | إعدادات تصفية المحتوى | +| **next_token** | `str` | لا | None | رمز لتصفح الصفحات | + +## متغيرات البيئة + +```bash +BEDROCK_KB_ID=your-knowledge-base-id # Alternative to passing knowledge_base_id +AWS_REGION=your-aws-region # Defaults to us-east-1 +AWS_ACCESS_KEY_ID=your-access-key # Required for AWS authentication +AWS_SECRET_ACCESS_KEY=your-secret-key # Required for AWS authentication +``` + +## تنسيق الاستجابة + +تعيد الأداة النتائج بتنسيق JSON: + +```json +{ + "results": [ + { + "content": "Retrieved text content", + "content_type": "text", + "source_type": "S3", + "source_uri": "s3://bucket/document.pdf", + "score": 0.95, + "metadata": { + "additional": "metadata" + } + } + ], + "nextToken": "pagination-token", + "guardrailAction": "NONE" +} +``` + +## الاستخدام المتقدم + +### إعداد استرجاع مخصص + +```python +kb_tool = BedrockKBRetrieverTool( + knowledge_base_id="your-kb-id", + retrieval_configuration={ + "vectorSearchConfiguration": { + "numberOfResults": 10, + "overrideSearchType": "HYBRID" + } + } +) + +policy_expert = Agent( + role='Policy Expert', + goal='Analyze company policies in detail', + backstory='I am an expert in corporate policy analysis with deep knowledge of regulatory requirements.', + tools=[kb_tool] +) +``` + +## مصادر البيانات المدعومة + +- Amazon S3 +- Confluence +- Salesforce +- SharePoint +- صفحات الويب +- مواقع مستندات مخصصة +- Amazon Kendra +- قواعد بيانات SQL + +## حالات الاستخدام + +### تكامل المعرفة المؤسسية +- تمكين وكلاء CrewAI من الوصول إلى المعرفة الخاصة بمؤسستك دون كشف البيانات الحساسة +- السماح للوكلاء باتخاذ قرارات بناءً على سياسات وإجراءات ووثائق شركتك المحددة +- إنشاء وكلاء يمكنهم الإجابة على الأسئلة بناءً على وثائقك الداخلية مع الحفاظ على أمان البيانات + +### المعرفة المتخصصة بالمجال +- ربط وكلاء CrewAI بقواعد معرفة متخصصة بالمجال (قانونية، طبية، تقنية) دون إعادة تدريب النماذج +- الاستفادة من مستودعات المعرفة الموجودة المُدارة بالفعل في بيئة AWS +- الجمع بين تفكير CrewAI والمعلومات المتخصصة من قواعد معرفتك + +### اتخاذ القرارات المبنية على البيانات +- تأسيس استجابات وكلاء CrewAI على بيانات شركتك الفعلية بدلاً من المعرفة العامة +- ضمان تقديم الوكلاء لتوصيات بناءً على سياق أعمالك ووثائقك المحددة +- تقليل التوهمات من خلال استرجاع معلومات واقعية من قواعد معرفتك + +### وصول معلوماتي قابل للتوسع +- الوصول إلى تيرابايت من المعرفة المؤسسية دون تضمينها كلها في نماذجك +- الاستعلام الديناميكي عن المعلومات ذات الصلة فقط اللازمة لمهام محددة +- الاستفادة من البنية التحتية القابلة للتوسع من AWS للتعامل مع قواعد معرفة كبيرة بكفاءة + +### الامتثال والحوكمة +- ضمان تقديم وكلاء CrewAI لاستجابات تتوافق مع وثائق شركتك المعتمدة +- إنشاء مسارات قابلة للتدقيق لمصادر المعلومات المستخدمة من قبل وكلائك +- الحفاظ على التحكم في مصادر المعلومات التي يمكن لوكلائك الوصول إليها diff --git a/docs/ar/tools/cloud-storage/overview.mdx b/docs/ar/tools/cloud-storage/overview.mdx new file mode 100644 index 000000000..8c905b51e --- /dev/null +++ b/docs/ar/tools/cloud-storage/overview.mdx @@ -0,0 +1,51 @@ +--- +title: "نظرة عامة" +description: "التفاعل مع الخدمات السحابية وأنظمة التخزين ومنصات الذكاء الاصطناعي السحابية" +icon: "face-smile" +mode: "wide" +--- + +تمكّن هذه الأدوات وكلاءك من التفاعل مع الخدمات السحابية والوصول إلى التخزين السحابي والاستفادة من منصات الذكاء الاصطناعي السحابية لعمليات قابلة للتوسع. + +## **الأدوات المتاحة** + + + + قراءة الملفات والبيانات من حاويات Amazon S3. + + + + كتابة وتحميل الملفات إلى تخزين Amazon S3. + + + + استدعاء وكلاء Amazon Bedrock للمهام المدعومة بالذكاء الاصطناعي. + + + + استرجاع المعلومات من قواعد معرفة Amazon Bedrock. + + + +## **حالات الاستخدام الشائعة** + +- **تخزين الملفات**: تخزين واسترجاع الملفات من أنظمة التخزين السحابية +- **نسخ البيانات احتياطياً**: نسخ البيانات المهمة احتياطياً إلى التخزين السحابي +- **خدمات الذكاء الاصطناعي**: الوصول إلى نماذج وخدمات الذكاء الاصطناعي السحابية +- **استرجاع المعرفة**: الاستعلام عن قواعد المعرفة المستضافة سحابياً +- **عمليات قابلة للتوسع**: الاستفادة من البنية التحتية السحابية للمعالجة + +```python +from crewai_tools import S3ReaderTool, S3WriterTool, BedrockInvokeAgentTool + +# Create cloud tools +s3_reader = S3ReaderTool() +s3_writer = S3WriterTool() +bedrock_agent = BedrockInvokeAgentTool() + +# Add to your agent +agent = Agent( + role="Cloud Operations Specialist", + tools=[s3_reader, s3_writer, bedrock_agent], + goal="Manage cloud resources and AI services" +) diff --git a/docs/ar/tools/cloud-storage/s3readertool.mdx b/docs/ar/tools/cloud-storage/s3readertool.mdx new file mode 100644 index 000000000..763e56074 --- /dev/null +++ b/docs/ar/tools/cloud-storage/s3readertool.mdx @@ -0,0 +1,145 @@ +--- +title: أداة قراءة S3 +description: تمكّن `S3ReaderTool` وكلاء CrewAI من قراءة الملفات من حاويات Amazon S3. +icon: aws +mode: "wide" +--- + +# `S3ReaderTool` + +## الوصف + +صُممت `S3ReaderTool` لقراءة الملفات من حاويات Amazon S3. تتيح هذه الأداة لوكلاء CrewAI الوصول إلى المحتوى المخزن في S3 واسترجاعه، مما يجعلها مثالية لسير العمل الذي يتطلب قراءة البيانات أو ملفات الإعداد أو أي محتوى آخر مخزن في تخزين AWS S3. + +## التثبيت + +لاستخدام هذه الأداة، تحتاج إلى تثبيت التبعيات المطلوبة: + +```shell +uv add boto3 +``` + +## خطوات البدء + +لاستخدام `S3ReaderTool` بفعالية، اتبع الخطوات التالية: + +1. **تثبيت التبعيات**: ثبّت الحزم المطلوبة باستخدام الأمر أعلاه. +2. **إعداد بيانات اعتماد AWS**: عيّن بيانات اعتماد AWS كمتغيرات بيئة. +3. **تهيئة الأداة**: أنشئ مثيلاً من الأداة. +4. **تحديد مسار S3**: قدّم مسار S3 للملف المراد قراءته. + +## مثال + +يوضح المثال التالي كيفية استخدام `S3ReaderTool` لقراءة ملف من حاوية S3: + +```python Code +from crewai import Agent, Task, Crew +from crewai_tools.aws.s3 import S3ReaderTool + +# Initialize the tool +s3_reader_tool = S3ReaderTool() + +# Define an agent that uses the tool +file_reader_agent = Agent( + role="File Reader", + goal="Read files from S3 buckets", + backstory="An expert in retrieving and processing files from cloud storage.", + tools=[s3_reader_tool], + verbose=True, +) + +# Example task to read a configuration file +read_task = Task( + description="Read the configuration file from {my_bucket} and summarize its contents.", + expected_output="A summary of the configuration file contents.", + agent=file_reader_agent, +) + +# Create and run the crew +crew = Crew(agents=[file_reader_agent], tasks=[read_task]) +result = crew.kickoff(inputs={"my_bucket": "s3://my-bucket/config/app-config.json"}) +``` + +## المعاملات + +تقبل `S3ReaderTool` المعامل التالي عند استخدامها من قبل وكيل: + +- **file_path**: مطلوب. مسار ملف S3 بتنسيق `s3://bucket-name/file-name`. + +## بيانات اعتماد AWS + +تتطلب الأداة بيانات اعتماد AWS للوصول إلى حاويات S3. يمكنك إعداد هذه البيانات باستخدام متغيرات البيئة: + +- **CREW_AWS_REGION**: منطقة AWS حيث تقع حاوية S3. القيمة الافتراضية `us-east-1`. +- **CREW_AWS_ACCESS_KEY_ID**: معرّف مفتاح الوصول لـ AWS. +- **CREW_AWS_SEC_ACCESS_KEY**: مفتاح الوصول السري لـ AWS. + +## الاستخدام + +عند استخدام `S3ReaderTool` مع وكيل، سيحتاج الوكيل لتقديم مسار ملف S3: + +```python Code +# Example of using the tool with an agent +file_reader_agent = Agent( + role="File Reader", + goal="Read files from S3 buckets", + backstory="An expert in retrieving and processing files from cloud storage.", + tools=[s3_reader_tool], + verbose=True, +) + +# Create a task for the agent to read a specific file +read_config_task = Task( + description="Read the application configuration file from {my_bucket} and extract the database connection settings.", + expected_output="The database connection settings from the configuration file.", + agent=file_reader_agent, +) + +# Run the task +crew = Crew(agents=[file_reader_agent], tasks=[read_config_task]) +result = crew.kickoff(inputs={"my_bucket": "s3://my-bucket/config/app-config.json"}) +``` + +## معالجة الأخطاء + +تتضمن `S3ReaderTool` معالجة أخطاء لمشكلات S3 الشائعة: + +- تنسيق مسار S3 غير صالح +- ملفات مفقودة أو غير قابلة للوصول +- مشكلات الأذونات +- مشكلات بيانات اعتماد AWS + +عند حدوث خطأ، ستعيد الأداة رسالة خطأ تتضمن تفاصيل حول المشكلة. + +## تفاصيل التنفيذ + +تستخدم `S3ReaderTool` حزمة AWS SDK لـ Python (boto3) للتفاعل مع S3: + +```python Code +class S3ReaderTool(BaseTool): + name: str = "S3 Reader Tool" + description: str = "Reads a file from Amazon S3 given an S3 file path" + + def _run(self, file_path: str) -> str: + try: + bucket_name, object_key = self._parse_s3_path(file_path) + + s3 = boto3.client( + 's3', + region_name=os.getenv('CREW_AWS_REGION', 'us-east-1'), + aws_access_key_id=os.getenv('CREW_AWS_ACCESS_KEY_ID'), + aws_secret_access_key=os.getenv('CREW_AWS_SEC_ACCESS_KEY') + ) + + # Read file content from S3 + response = s3.get_object(Bucket=bucket_name, Key=object_key) + file_content = response['Body'].read().decode('utf-8') + + return file_content + except ClientError as e: + return f"Error reading file from S3: {str(e)}" +``` + +## الخلاصة + +توفر `S3ReaderTool` طريقة مباشرة لقراءة الملفات من حاويات Amazon S3. من خلال تمكين الوكلاء من الوصول إلى المحتوى المخزن في S3، تسهّل سير العمل الذي يتطلب وصولاً سحابياً للملفات. هذه الأداة مفيدة بشكل خاص لمعالجة البيانات وإدارة الإعدادات وأي مهمة تتضمن استرجاع المعلومات من تخزين AWS S3. diff --git a/docs/ar/tools/cloud-storage/s3writertool.mdx b/docs/ar/tools/cloud-storage/s3writertool.mdx new file mode 100644 index 000000000..68fecc5dd --- /dev/null +++ b/docs/ar/tools/cloud-storage/s3writertool.mdx @@ -0,0 +1,151 @@ +--- +title: أداة كتابة S3 +description: تمكّن `S3WriterTool` وكلاء CrewAI من كتابة المحتوى إلى ملفات في حاويات Amazon S3. +icon: aws +mode: "wide" +--- + +# `S3WriterTool` + +## الوصف + +صُممت `S3WriterTool` لكتابة المحتوى إلى ملفات في حاويات Amazon S3. تتيح هذه الأداة لوكلاء CrewAI إنشاء أو تحديث الملفات في S3، مما يجعلها مثالية لسير العمل الذي يتطلب تخزين البيانات أو حفظ ملفات الإعداد أو حفظ أي محتوى آخر في تخزين AWS S3. + +## التثبيت + +لاستخدام هذه الأداة، تحتاج إلى تثبيت التبعيات المطلوبة: + +```shell +uv add boto3 +``` + +## خطوات البدء + +لاستخدام `S3WriterTool` بفعالية، اتبع الخطوات التالية: + +1. **تثبيت التبعيات**: ثبّت الحزم المطلوبة باستخدام الأمر أعلاه. +2. **إعداد بيانات اعتماد AWS**: عيّن بيانات اعتماد AWS كمتغيرات بيئة. +3. **تهيئة الأداة**: أنشئ مثيلاً من الأداة. +4. **تحديد مسار S3 والمحتوى**: قدّم مسار S3 حيث تريد كتابة الملف والمحتوى المراد كتابته. + +## مثال + +يوضح المثال التالي كيفية استخدام `S3WriterTool` لكتابة محتوى إلى ملف في حاوية S3: + +```python Code +from crewai import Agent, Task, Crew +from crewai_tools.aws.s3 import S3WriterTool + +# Initialize the tool +s3_writer_tool = S3WriterTool() + +# Define an agent that uses the tool +file_writer_agent = Agent( + role="File Writer", + goal="Write content to files in S3 buckets", + backstory="An expert in storing and managing files in cloud storage.", + tools=[s3_writer_tool], + verbose=True, +) + +# Example task to write a report +write_task = Task( + description="Generate a summary report of the quarterly sales data and save it to {my_bucket}.", + expected_output="Confirmation that the report was successfully saved to S3.", + agent=file_writer_agent, +) + +# Create and run the crew +crew = Crew(agents=[file_writer_agent], tasks=[write_task]) +result = crew.kickoff(inputs={"my_bucket": "s3://my-bucket/reports/quarterly-summary.txt"}) +``` + +## المعاملات + +تقبل `S3WriterTool` المعاملات التالية عند استخدامها من قبل وكيل: + +- **file_path**: مطلوب. مسار ملف S3 بتنسيق `s3://bucket-name/file-name`. +- **content**: مطلوب. المحتوى المراد كتابته في الملف. + +## بيانات اعتماد AWS + +تتطلب الأداة بيانات اعتماد AWS للوصول إلى حاويات S3. يمكنك إعداد هذه البيانات باستخدام متغيرات البيئة: + +- **CREW_AWS_REGION**: منطقة AWS حيث تقع حاوية S3. القيمة الافتراضية `us-east-1`. +- **CREW_AWS_ACCESS_KEY_ID**: معرّف مفتاح الوصول لـ AWS. +- **CREW_AWS_SEC_ACCESS_KEY**: مفتاح الوصول السري لـ AWS. + +## الاستخدام + +عند استخدام `S3WriterTool` مع وكيل، سيحتاج الوكيل لتقديم كل من مسار ملف S3 والمحتوى المراد كتابته: + +```python Code +# Example of using the tool with an agent +file_writer_agent = Agent( + role="File Writer", + goal="Write content to files in S3 buckets", + backstory="An expert in storing and managing files in cloud storage.", + tools=[s3_writer_tool], + verbose=True, +) + +# Create a task for the agent to write a specific file +write_config_task = Task( + description=""" + Create a configuration file with the following database settings: + - host: db.example.com + - port: 5432 + - username: app_user + - password: secure_password + + Save this configuration as JSON to {my_bucket}. + """, + expected_output="Confirmation that the configuration file was successfully saved to S3.", + agent=file_writer_agent, +) + +# Run the task +crew = Crew(agents=[file_writer_agent], tasks=[write_config_task]) +result = crew.kickoff(inputs={"my_bucket": "s3://my-bucket/config/db-config.json"}) +``` + +## معالجة الأخطاء + +تتضمن `S3WriterTool` معالجة أخطاء لمشكلات S3 الشائعة: + +- تنسيق مسار S3 غير صالح +- مشكلات الأذونات (مثل عدم وجود صلاحية كتابة للحاوية) +- مشكلات بيانات اعتماد AWS +- الحاوية غير موجودة + +عند حدوث خطأ، ستعيد الأداة رسالة خطأ تتضمن تفاصيل حول المشكلة. + +## تفاصيل التنفيذ + +تستخدم `S3WriterTool` حزمة AWS SDK لـ Python (boto3) للتفاعل مع S3: + +```python Code +class S3WriterTool(BaseTool): + name: str = "S3 Writer Tool" + description: str = "Writes content to a file in Amazon S3 given an S3 file path" + + def _run(self, file_path: str, content: str) -> str: + try: + bucket_name, object_key = self._parse_s3_path(file_path) + + s3 = boto3.client( + 's3', + region_name=os.getenv('CREW_AWS_REGION', 'us-east-1'), + aws_access_key_id=os.getenv('CREW_AWS_ACCESS_KEY_ID'), + aws_secret_access_key=os.getenv('CREW_AWS_SEC_ACCESS_KEY') + ) + + s3.put_object(Bucket=bucket_name, Key=object_key, Body=content.encode('utf-8')) + return f"Successfully wrote content to {file_path}" + except ClientError as e: + return f"Error writing file to S3: {str(e)}" +``` + +## الخلاصة + +توفر `S3WriterTool` طريقة مباشرة لكتابة المحتوى إلى ملفات في حاويات Amazon S3. من خلال تمكين الوكلاء من إنشاء وتحديث الملفات في S3، تسهّل سير العمل الذي يتطلب تخزين ملفات سحابي. هذه الأداة مفيدة بشكل خاص لحفظ البيانات وإدارة الإعدادات وتوليد التقارير وأي مهمة تتضمن تخزين المعلومات في تخزين AWS S3. diff --git a/docs/ar/tools/database-data/mongodbvectorsearchtool.mdx b/docs/ar/tools/database-data/mongodbvectorsearchtool.mdx new file mode 100644 index 000000000..cbff43b11 --- /dev/null +++ b/docs/ar/tools/database-data/mongodbvectorsearchtool.mdx @@ -0,0 +1,167 @@ +--- +title: أداة البحث المتجهي في MongoDB +description: تقوم `MongoDBVectorSearchTool` بإجراء بحث متجهي على MongoDB Atlas مع أدوات مساعدة اختيارية لإنشاء الفهارس. +icon: "leaf" +mode: "wide" +--- + +# `MongoDBVectorSearchTool` + +## الوصف + +تنفيذ استعلامات التشابه المتجهي على مجموعات MongoDB Atlas. تدعم أدوات مساعدة لإنشاء الفهارس وإدراج النصوص المضمنة بكميات كبيرة. + +يدعم MongoDB Atlas البحث المتجهي الأصلي. اعرف المزيد: +https://www.mongodb.com/docs/atlas/atlas-vector-search/vector-search-overview/ + +## التثبيت + +قم بالتثبيت مع إضافة MongoDB: + +```shell +pip install crewai-tools[mongodb] +``` + +أو + +```shell +uv add crewai-tools --extra mongodb +``` + +## المعاملات + +### التهيئة + +- `connection_string` (str, مطلوب) +- `database_name` (str, مطلوب) +- `collection_name` (str, مطلوب) +- `vector_index_name` (str, الافتراضي `vector_index`) +- `text_key` (str, الافتراضي `text`) +- `embedding_key` (str, الافتراضي `embedding`) +- `dimensions` (int, الافتراضي `1536`) + +### معاملات التشغيل + +- `query` (str, مطلوب): استعلام بلغة طبيعية لتضمينه والبحث عنه. + +## بداية سريعة + +```python Code +from crewai_tools import MongoDBVectorSearchTool + +tool = MongoDBVectorSearchTool( + connection_string="mongodb+srv://...", + database_name="mydb", + collection_name="docs", +) + +print(tool.run(query="how to create vector index")) +``` + +## أدوات مساعدة لإنشاء الفهارس + +استخدم `create_vector_search_index(...)` لإنشاء فهرس بحث متجهي في Atlas بالأبعاد والتشابه الصحيحين. + +## المشكلات الشائعة + +- فشل المصادقة: تأكد من أن قائمة الوصول إلى عناوين IP في Atlas تسمح بخادمك وأن سلسلة الاتصال تتضمن بيانات الاعتماد. +- الفهرس غير موجود: أنشئ الفهرس المتجهي أولاً؛ يجب أن يتطابق الاسم مع `vector_index_name`. +- عدم تطابق الأبعاد: قم بمحاذاة أبعاد نموذج التضمين مع `dimensions`. + +## أمثلة إضافية + +### التهيئة الأساسية + +```python Code +from crewai_tools import MongoDBVectorSearchTool + +tool = MongoDBVectorSearchTool( + database_name="example_database", + collection_name="example_collection", + connection_string="", +) +``` + +### تكوين استعلام مخصص + +```python Code +from crewai_tools import MongoDBVectorSearchConfig, MongoDBVectorSearchTool + +query_config = MongoDBVectorSearchConfig(limit=10, oversampling_factor=2) +tool = MongoDBVectorSearchTool( + database_name="example_database", + collection_name="example_collection", + connection_string="", + query_config=query_config, + vector_index_name="my_vector_index", +) + +rag_agent = Agent( + name="rag_agent", + role="You are a helpful assistant that can answer questions with the help of the MongoDBVectorSearchTool.", + goal="...", + backstory="...", + tools=[tool], +) +``` + +### تحميل قاعدة البيانات مسبقاً وإنشاء الفهرس + +```python Code +import os +from crewai_tools import MongoDBVectorSearchTool + +tool = MongoDBVectorSearchTool( + database_name="example_database", + collection_name="example_collection", + connection_string="", +) + +# Load text content from a local folder and add to MongoDB +texts = [] +for fname in os.listdir("knowledge"): + path = os.path.join("knowledge", fname) + if os.path.isfile(path): + with open(path, "r", encoding="utf-8") as f: + texts.append(f.read()) + +tool.add_texts(texts) + +# Create the Atlas Vector Search index (e.g., 3072 dims for text-embedding-3-large) +tool.create_vector_search_index(dimensions=3072) +``` + +## مثال + +```python Code +from crewai import Agent, Task, Crew +from crewai_tools import MongoDBVectorSearchTool + +tool = MongoDBVectorSearchTool( + connection_string="mongodb+srv://...", + database_name="mydb", + collection_name="docs", +) + +agent = Agent( + role="RAG Agent", + goal="Answer using MongoDB vector search", + backstory="Knowledge retrieval specialist", + tools=[tool], + verbose=True, +) + +task = Task( + description="Find relevant content for 'indexing guidance'", + expected_output="A concise answer citing the most relevant matches", + agent=agent, +) + +crew = Crew( + agents=[agent], + tasks=[task], + verbose=True, +) + +result = crew.kickoff() +``` diff --git a/docs/ar/tools/database-data/mysqltool.mdx b/docs/ar/tools/database-data/mysqltool.mdx new file mode 100644 index 000000000..4f8bb050c --- /dev/null +++ b/docs/ar/tools/database-data/mysqltool.mdx @@ -0,0 +1,67 @@ +--- +title: بحث RAG في MySQL +description: أداة `MySQLSearchTool` مصممة للبحث في قواعد بيانات MySQL وإرجاع النتائج الأكثر صلة. +icon: database +mode: "wide" +--- + +## نظرة عامة + +هذه الأداة مصممة لتسهيل عمليات البحث الدلالي داخل جداول قواعد بيانات MySQL. من خلال الاستفادة من تقنية RAG (الاسترجاع والتوليد)، توفر أداة MySQLSearchTool للمستخدمين وسيلة فعالة للاستعلام عن محتوى جداول قواعد البيانات، مصممة خصيصاً لقواعد بيانات MySQL. تبسط عملية العثور على البيانات ذات الصلة من خلال استعلامات البحث الدلالي، مما يجعلها مورداً لا يُقدَّر بثمن للمستخدمين الذين يحتاجون إلى إجراء استعلامات متقدمة على مجموعات بيانات واسعة داخل قاعدة بيانات MySQL. + +## التثبيت + +لتثبيت حزمة `crewai_tools` واستخدام MySQLSearchTool، نفّذ الأمر التالي في الطرفية: + +```shell +pip install 'crewai[tools]' +``` + +## مثال + +فيما يلي مثال يوضح كيفية استخدام MySQLSearchTool لإجراء بحث دلالي على جدول داخل قاعدة بيانات MySQL: + +```python Code +from crewai_tools import MySQLSearchTool + +# Initialize the tool with the database URI and the target table name +tool = MySQLSearchTool( + db_uri='mysql://user:password@localhost:3306/mydatabase', + table_name='employees' +) +``` + +## المعاملات + +تتطلب أداة MySQLSearchTool المعاملات التالية لتشغيلها: + +- `db_uri`: سلسلة نصية تمثل عنوان URI لقاعدة بيانات MySQL المراد الاستعلام عنها. هذا المعامل إلزامي ويجب أن يتضمن تفاصيل المصادقة اللازمة وموقع قاعدة البيانات. +- `table_name`: سلسلة نصية تحدد اسم الجدول داخل قاعدة البيانات الذي سيتم إجراء البحث الدلالي عليه. هذا المعامل إلزامي. + +## النموذج والتضمينات المخصصة + +بشكل افتراضي، تستخدم الأداة OpenAI لكل من التضمينات والتلخيص. لتخصيص النموذج، يمكنك استخدام قاموس تكوين كما يلي: + +```python Code +tool = MySQLSearchTool( + config=dict( + llm=dict( + provider="ollama", # or google, openai, anthropic, llama2, ... + config=dict( + model="llama2", + # temperature=0.5, + # top_p=1, + # stream=true, + ), + ), + embedder=dict( + provider="google-generativeai", + config=dict( + model_name="gemini-embedding-001", + task_type="RETRIEVAL_DOCUMENT", + # title="Embeddings", + ), + ), + ) +) +``` diff --git a/docs/ar/tools/database-data/nl2sqltool.mdx b/docs/ar/tools/database-data/nl2sqltool.mdx new file mode 100644 index 000000000..de52a5dd8 --- /dev/null +++ b/docs/ar/tools/database-data/nl2sqltool.mdx @@ -0,0 +1,102 @@ +--- +title: أداة NL2SQL +description: أداة `NL2SQLTool` مصممة لتحويل اللغة الطبيعية إلى استعلامات SQL. +icon: language +mode: "wide" +--- + +## نظرة عامة + +تُستخدم هذه الأداة لتحويل اللغة الطبيعية إلى استعلامات SQL. عند تمريرها إلى الوكيل، ستقوم بتوليد الاستعلامات ثم استخدامها للتفاعل مع قاعدة البيانات. + +يتيح ذلك سير عمل متعددة مثل أن يقوم وكيل بالوصول إلى قاعدة البيانات واسترجاع المعلومات بناءً على الهدف ثم استخدام تلك المعلومات لتوليد استجابة أو تقرير أو أي مخرجات أخرى. بالإضافة إلى ذلك، يوفر القدرة للوكيل على تحديث قاعدة البيانات بناءً على هدفه. + +**تنبيه**: تأكد من أن الوكيل لديه وصول إلى نسخة قراءة فقط أو أنه من المقبول أن يقوم الوكيل بتنفيذ استعلامات إدراج/تحديث على قاعدة البيانات. + +## نموذج الأمان + +`NL2SQLTool` هي أداة قابلة للتنفيذ. تقوم بتشغيل استعلامات SQL المولّدة من النموذج مباشرة على اتصال قاعدة البيانات المُهيأ. + +هذا يعني أن المخاطر تعتمد على خيارات النشر الخاصة بك: + +- بيانات الاعتماد التي تقدمها في `db_uri` +- ما إذا كان بإمكان المدخلات غير الموثوقة التأثير على الأوامر +- ما إذا كنت تضيف حواجز حماية لاستدعاءات الأدوات قبل التنفيذ + +إذا كنت توجه مدخلات غير موثوقة إلى وكلاء يستخدمون هذه الأداة، تعامل معها كتكامل عالي المخاطر. + +## توصيات التقوية + +استخدم جميع الإجراءات التالية في بيئة الإنتاج: + +- استخدم مستخدم قاعدة بيانات للقراءة فقط كلما أمكن +- فضّل نسخة القراءة لأعباء العمل التحليلية/الاسترجاعية +- امنح أقل صلاحيات ممكنة (بدون أدوار المسؤول/المستخدم الفائق، بدون صلاحيات على مستوى الملفات/النظام) +- طبّق حدود الموارد على مستوى قاعدة البيانات (مهلة الاستعلام، مهلة القفل، حدود التكلفة/الصفوف) +- أضف خطافات `before_tool_call` لفرض أنماط الاستعلام المسموح بها +- فعّل تسجيل الاستعلامات والتنبيهات للعبارات التدميرية + +## المتطلبات + +- SqlAlchemy +- أي مكتبة متوافقة مع قواعد البيانات (مثل psycopg2، mysql-connector-python) + +## التثبيت + +قم بتثبيت حزمة crewai_tools + +```shell +pip install 'crewai[tools]' +``` + +## الاستخدام + +لاستخدام أداة NL2SQLTool، تحتاج إلى تمرير عنوان URI لقاعدة البيانات إلى الأداة. يجب أن يكون العنوان بصيغة `dialect+driver://username:password@host:port/database`. + +```python Code +from crewai_tools import NL2SQLTool + +# psycopg2 was installed to run this example with PostgreSQL +nl2sql = NL2SQLTool(db_uri="postgresql://example@localhost:5432/test_db") + +@agent +def researcher(self) -> Agent: + return Agent( + config=self.agents_config["researcher"], + allow_delegation=False, + tools=[nl2sql] + ) +``` + +## مثال + +كان هدف المهمة الأساسي: + +"استرجاع المتوسط والحد الأقصى والحد الأدنى للإيرادات الشهرية لكل مدينة، مع تضمين المدن التي بها أكثر من مستخدم واحد فقط. أيضاً، قم بعدّ المستخدمين في كل مدينة وترتيب النتائج حسب متوسط الإيرادات الشهرية بترتيب تنازلي" + +حاول الوكيل الحصول على المعلومات من قاعدة البيانات، الاستعلام الأول كان خاطئاً فحاول الوكيل مرة أخرى وحصل على المعلومات الصحيحة ومررها إلى الوكيل التالي. + +![alt text](https://github.com/crewAIInc/crewAI-tools/blob/main/crewai_tools/tools/nl2sql/images/image-2.png?raw=true) +![alt text](https://github.com/crewAIInc/crewAI-tools/raw/main/crewai_tools/tools/nl2sql/images/image-3.png) + + +كان هدف المهمة الثانية: + +"مراجعة البيانات وإنشاء تقرير مفصّل، ثم إنشاء جدول في قاعدة البيانات بحقول مبنية على البيانات المقدمة. تضمين معلومات عن المتوسط والحد الأقصى والحد الأدنى للإيرادات الشهرية لكل مدينة، مع تضمين المدن التي بها أكثر من مستخدم واحد فقط. أيضاً، عدّ المستخدمين في كل مدينة وترتيب النتائج حسب متوسط الإيرادات الشهرية بترتيب تنازلي." + +الآن تصبح الأمور مثيرة للاهتمام، حيث يولّد الوكيل استعلام SQL ليس فقط لإنشاء الجدول بل أيضاً لإدراج البيانات فيه. وفي النهاية لا يزال الوكيل يُرجع التقرير النهائي الذي يتطابق تماماً مع ما كان في قاعدة البيانات. + +![alt text](https://github.com/crewAIInc/crewAI-tools/raw/main/crewai_tools/tools/nl2sql/images/image-4.png) +![alt text](https://github.com/crewAIInc/crewAI-tools/raw/main/crewai_tools/tools/nl2sql/images/image-5.png) + +![alt text](https://github.com/crewAIInc/crewAI-tools/raw/main/crewai_tools/tools/nl2sql/images/image-9.png) +![alt text](https://github.com/crewAIInc/crewAI-tools/raw/main/crewai_tools/tools/nl2sql/images/image-7.png) + + +هذا مثال بسيط على كيفية استخدام أداة NL2SQLTool للتفاعل مع قاعدة البيانات وتوليد التقارير بناءً على البيانات الموجودة فيها. + +توفر الأداة إمكانيات لا حصر لها لمنطق الوكيل وكيفية تفاعله مع قاعدة البيانات. + +```md + DB -> Agent -> ... -> Agent -> DB +``` diff --git a/docs/ar/tools/database-data/overview.mdx b/docs/ar/tools/database-data/overview.mdx new file mode 100644 index 000000000..f4824f515 --- /dev/null +++ b/docs/ar/tools/database-data/overview.mdx @@ -0,0 +1,67 @@ +--- +title: "نظرة عامة" +description: "الاتصال بقواعد البيانات ومخازن المتجهات ومستودعات البيانات للحصول على وصول شامل للبيانات" +icon: "face-smile" +mode: "wide" +--- + +تتيح هذه الأدوات لوكلائك التفاعل مع أنظمة قواعد بيانات متنوعة، من قواعد بيانات SQL التقليدية إلى مخازن المتجهات الحديثة ومستودعات البيانات. + +## **الأدوات المتاحة** + + + + الاتصال بقواعد بيانات MySQL والاستعلام عنها بعمليات SQL. + + + + البحث والاستعلام في قواعد بيانات PostgreSQL بكفاءة. + + + + الوصول إلى مستودع بيانات Snowflake للتحليلات وإعداد التقارير. + + + + تحويل استعلامات اللغة الطبيعية إلى عبارات SQL تلقائياً. + + + + البحث في التضمينات المتجهية باستخدام قاعدة بيانات Qdrant المتجهية. + + + + إجراء بحث دلالي باستخدام قاعدة بيانات Weaviate المتجهية. + + + + بحث التشابه المتجهي على MongoDB Atlas مع أدوات مساعدة للفهرسة. + + + + استعلامات SELECT/SHOW آمنة على SingleStore مع تجميع الاتصالات والتحقق. + + + +## **حالات الاستخدام الشائعة** + +- **تحليل البيانات**: الاستعلام عن قواعد البيانات لذكاء الأعمال وإعداد التقارير +- **البحث المتجهي**: العثور على محتوى مشابه باستخدام التضمينات الدلالية +- **عمليات ETL**: استخراج البيانات وتحويلها وتحميلها بين الأنظمة +- **التحليلات الفورية**: الوصول إلى البيانات الحية لاتخاذ القرارات + +```python +from crewai_tools import MySQLTool, QdrantVectorSearchTool, NL2SQLTool + +# Create database tools +mysql_db = MySQLTool() +vector_search = QdrantVectorSearchTool() +nl_to_sql = NL2SQLTool() + +# Add to your agent +agent = Agent( + role="Data Analyst", + tools=[mysql_db, vector_search, nl_to_sql], + goal="Extract insights from various data sources" +) +``` diff --git a/docs/ar/tools/database-data/pgsearchtool.mdx b/docs/ar/tools/database-data/pgsearchtool.mdx new file mode 100644 index 000000000..ca959aad5 --- /dev/null +++ b/docs/ar/tools/database-data/pgsearchtool.mdx @@ -0,0 +1,80 @@ +--- +title: بحث RAG في PostgreSQL +description: أداة `PGSearchTool` مصممة للبحث في قواعد بيانات PostgreSQL وإرجاع النتائج الأكثر صلة. +icon: elephant +mode: "wide" +--- + +## نظرة عامة + + + أداة PGSearchTool قيد التطوير حالياً. يوضح هذا المستند الوظائف والواجهة المقصودة. + مع تقدم التطوير، يرجى الانتباه إلى أن بعض الميزات قد لا تكون متاحة أو قد تتغير. + + +## الوصف + +صُممت أداة PGSearchTool كأداة قوية لتسهيل عمليات البحث الدلالي داخل جداول قواعد بيانات PostgreSQL. من خلال الاستفادة من تقنية الاسترجاع والتوليد (RAG) المتقدمة، تهدف إلى توفير وسيلة فعالة للاستعلام عن محتوى جداول قواعد البيانات، مصممة خصيصاً لقواعد بيانات PostgreSQL. هدف الأداة هو تبسيط عملية العثور على البيانات ذات الصلة من خلال استعلامات البحث الدلالي، مما يوفر مورداً قيماً للمستخدمين الذين يحتاجون إلى إجراء استعلامات متقدمة على مجموعات بيانات واسعة في بيئة PostgreSQL. + +## التثبيت + +يمكن تثبيت حزمة `crewai_tools`، التي ستتضمن أداة PGSearchTool عند إصدارها، باستخدام الأمر التالي: + +```shell +pip install 'crewai[tools]' +``` + + + أداة PGSearchTool غير متاحة بعد في الإصدار الحالي من حزمة `crewai_tools`. سيتم تحديث أمر التثبيت هذا بمجرد إصدار الأداة. + + +## مثال على الاستخدام + +فيما يلي مثال مقترح يوضح كيفية استخدام أداة PGSearchTool لإجراء بحث دلالي على جدول داخل قاعدة بيانات PostgreSQL: + +```python Code +from crewai_tools import PGSearchTool + +# Initialize the tool with the database URI and the target table name +tool = PGSearchTool( + db_uri='postgresql://user:password@localhost:5432/mydatabase', + table_name='employees' +) +``` + +## المعاملات + +صُممت أداة PGSearchTool لتتطلب المعاملات التالية لتشغيلها: + +| المعامل | النوع | الوصف | +|:---------------|:---------|:-------------------------------------------------------------------------------------------------------------------------------------| +| **db_uri** | `string` | **إلزامي**. سلسلة نصية تمثل عنوان URI لقاعدة بيانات PostgreSQL المراد الاستعلام عنها. هذا المعامل إلزامي ويجب أن يتضمن تفاصيل المصادقة اللازمة وموقع قاعدة البيانات. | +| **table_name** | `string` | **إلزامي**. سلسلة نصية تحدد اسم الجدول داخل قاعدة البيانات الذي سيتم إجراء البحث الدلالي عليه. هذا المعامل إلزامي أيضاً. | + +## النموذج والتضمينات المخصصة + +تنوي الأداة استخدام OpenAI لكل من التضمينات والتلخيص بشكل افتراضي. سيكون لدى المستخدمين خيار تخصيص النموذج باستخدام قاموس تكوين كما يلي: + +```python Code +tool = PGSearchTool( + config=dict( + llm=dict( + provider="ollama", # or google, openai, anthropic, llama2, ... + config=dict( + model="llama2", + # temperature=0.5, + # top_p=1, + # stream=true, + ), + ), + embedder=dict( + provider="google-generativeai", # or openai, ollama, ... + config=dict( + model_name="gemini-embedding-001", + task_type="RETRIEVAL_DOCUMENT", + # title="Embeddings", + ), + ), + ) +) +``` diff --git a/docs/ar/tools/database-data/qdrantvectorsearchtool.mdx b/docs/ar/tools/database-data/qdrantvectorsearchtool.mdx new file mode 100644 index 000000000..b77ed5a4b --- /dev/null +++ b/docs/ar/tools/database-data/qdrantvectorsearchtool.mdx @@ -0,0 +1,344 @@ +--- +title: 'أداة البحث المتجهي Qdrant' +description: 'إمكانيات البحث الدلالي لوكلاء CrewAI باستخدام قاعدة بيانات Qdrant المتجهية' +icon: vector-square +mode: "wide" +--- + +## نظرة عامة + +تتيح أداة البحث المتجهي Qdrant إمكانيات البحث الدلالي في وكلاء CrewAI من خلال الاستفادة من [Qdrant](https://qdrant.tech/)، محرك بحث التشابه المتجهي. تسمح هذه الأداة لوكلائك بالبحث في المستندات المخزنة في مجموعة Qdrant باستخدام التشابه الدلالي. + +## التثبيت + +قم بتثبيت الحزم المطلوبة: + +```bash +uv add qdrant-client +``` + +## الاستخدام الأساسي + +إليك مثال بسيط لكيفية استخدام الأداة: + +```python +from crewai import Agent +from crewai_tools import QdrantVectorSearchTool, QdrantConfig + +# Initialize the tool with QdrantConfig +qdrant_tool = QdrantVectorSearchTool( + qdrant_config=QdrantConfig( + qdrant_url="your_qdrant_url", + qdrant_api_key="your_qdrant_api_key", + collection_name="your_collection" + ) +) + +# Create an agent that uses the tool +agent = Agent( + role="Research Assistant", + goal="Find relevant information in documents", + tools=[qdrant_tool] +) + +# The tool will automatically use OpenAI embeddings +# and return the 3 most relevant results with scores > 0.35 +``` + +## مثال عملي كامل + +إليك مثالاً كاملاً يوضح كيفية: +1. استخراج النص من ملف PDF +2. توليد التضمينات باستخدام OpenAI +3. التخزين في Qdrant +4. إنشاء سير عمل RAG وكيلي باستخدام CrewAI للبحث الدلالي + +```python +import os +import uuid +import pdfplumber +from openai import OpenAI +from dotenv import load_dotenv +from crewai import Agent, Task, Crew, Process, LLM +from crewai_tools import QdrantVectorSearchTool +from qdrant_client import QdrantClient +from qdrant_client.models import PointStruct, Distance, VectorParams + +# Load environment variables +load_dotenv() + +# Initialize OpenAI client +client = OpenAI(api_key=os.getenv("OPENAI_API_KEY")) + +# Extract text from PDF +def extract_text_from_pdf(pdf_path): + text = [] + with pdfplumber.open(pdf_path) as pdf: + for page in pdf.pages: + page_text = page.extract_text() + if page_text: + text.append(page_text.strip()) + return text + +# Generate OpenAI embeddings +def get_openai_embedding(text): + response = client.embeddings.create( + input=text, + model="text-embedding-3-large" + ) + return response.data[0].embedding + +# Store text and embeddings in Qdrant +def load_pdf_to_qdrant(pdf_path, qdrant, collection_name): + # Extract text from PDF + text_chunks = extract_text_from_pdf(pdf_path) + + # Create Qdrant collection + if qdrant.collection_exists(collection_name): + qdrant.delete_collection(collection_name) + qdrant.create_collection( + collection_name=collection_name, + vectors_config=VectorParams(size=3072, distance=Distance.COSINE) + ) + + # Store embeddings + points = [] + for chunk in text_chunks: + embedding = get_openai_embedding(chunk) + points.append(PointStruct( + id=str(uuid.uuid4()), + vector=embedding, + payload={"text": chunk} + )) + qdrant.upsert(collection_name=collection_name, points=points) + +# Initialize Qdrant client and load data +qdrant = QdrantClient( + url=os.getenv("QDRANT_URL"), + api_key=os.getenv("QDRANT_API_KEY") +) +collection_name = "example_collection" +pdf_path = "path/to/your/document.pdf" +load_pdf_to_qdrant(pdf_path, qdrant, collection_name) + +# Initialize Qdrant search tool +from crewai_tools import QdrantConfig + +qdrant_tool = QdrantVectorSearchTool( + qdrant_config=QdrantConfig( + qdrant_url=os.getenv("QDRANT_URL"), + qdrant_api_key=os.getenv("QDRANT_API_KEY"), + collection_name=collection_name, + limit=3, + score_threshold=0.35 + ) +) + +# Create CrewAI agents +search_agent = Agent( + role="Senior Semantic Search Agent", + goal="Find and analyze documents based on semantic search", + backstory="""You are an expert research assistant who can find relevant + information using semantic search in a Qdrant database.""", + tools=[qdrant_tool], + verbose=True +) + +answer_agent = Agent( + role="Senior Answer Assistant", + goal="Generate answers to questions based on the context provided", + backstory="""You are an expert answer assistant who can generate + answers to questions based on the context provided.""", + tools=[qdrant_tool], + verbose=True +) + +# Define tasks +search_task = Task( + description="""Search for relevant documents about the {query}. + Your final answer should include: + - The relevant information found + - The similarity scores of the results + - The metadata of the relevant documents""", + agent=search_agent +) + +answer_task = Task( + description="""Given the context and metadata of relevant documents, + generate a final answer based on the context.""", + agent=answer_agent +) + +# Run CrewAI workflow +crew = Crew( + agents=[search_agent, answer_agent], + tasks=[search_task, answer_task], + process=Process.sequential, + verbose=True +) + +result = crew.kickoff( + inputs={"query": "What is the role of X in the document?"} +) +print(result) +``` + +## معاملات الأداة + +### المعاملات المطلوبة +- `qdrant_config` (QdrantConfig): كائن التكوين الذي يحتوي على جميع إعدادات Qdrant + +### معاملات QdrantConfig +- `qdrant_url` (str): عنوان URL لخادم Qdrant الخاص بك +- `qdrant_api_key` (str, اختياري): مفتاح API للمصادقة مع Qdrant +- `collection_name` (str): اسم مجموعة Qdrant المراد البحث فيها +- `limit` (int): الحد الأقصى لعدد النتائج المُرجعة (الافتراضي: 3) +- `score_threshold` (float): الحد الأدنى لدرجة التشابه (الافتراضي: 0.35) +- `filter` (Any, اختياري): نسخة Filter من Qdrant للتصفية المتقدمة (الافتراضي: None) + +### المعاملات الاختيارية للأداة +- `custom_embedding_fn` (Callable[[str], list[float]]): دالة مخصصة لتحويل النص إلى متجهات +- `qdrant_package` (str): مسار الحزمة الأساسية لـ Qdrant (الافتراضي: "qdrant_client") +- `client` (Any): عميل Qdrant مُهيأ مسبقاً (اختياري) + +## التصفية المتقدمة + +تدعم أداة QdrantVectorSearchTool إمكانيات تصفية قوية لتحسين نتائج البحث: + +### التصفية الديناميكية +استخدم معاملات `filter_by` و `filter_value` في بحثك لتصفية النتائج أثناء التنفيذ: + +```python +# Agent will use these parameters when calling the tool +# The tool schema accepts filter_by and filter_value +# Example: search with category filter +# Results will be filtered where category == "technology" +``` + +### المرشحات المسبقة مع QdrantConfig +للتصفية المعقدة، استخدم نسخ Filter من Qdrant في تكوينك: + +```python +from qdrant_client.http import models as qmodels +from crewai_tools import QdrantVectorSearchTool, QdrantConfig + +# Create a filter for specific conditions +preset_filter = qmodels.Filter( + must=[ + qmodels.FieldCondition( + key="category", + match=qmodels.MatchValue(value="research") + ), + qmodels.FieldCondition( + key="year", + match=qmodels.MatchValue(value=2024) + ) + ] +) + +# Initialize tool with preset filter +qdrant_tool = QdrantVectorSearchTool( + qdrant_config=QdrantConfig( + qdrant_url="your_url", + qdrant_api_key="your_key", + collection_name="your_collection", + filter=preset_filter # Preset filter applied to all searches + ) +) +``` + +### دمج المرشحات +تقوم الأداة تلقائياً بدمج المرشحات المسبقة من `QdrantConfig` مع المرشحات الديناميكية من `filter_by` و `filter_value`: + +```python +# If QdrantConfig has a preset filter for category="research" +# And the search uses filter_by="year", filter_value=2024 +# Both filters will be combined (AND logic) +``` + +## معاملات البحث + +تقبل الأداة هذه المعاملات في مخططها: +- `query` (str): استعلام البحث للعثور على مستندات مشابهة +- `filter_by` (str, اختياري): حقل البيانات الوصفية للتصفية عليه +- `filter_value` (Any, اختياري): القيمة المراد التصفية بها + +## صيغة الإرجاع + +تُرجع الأداة النتائج بصيغة JSON: + +```json +[ + { + "metadata": { + // Any metadata stored with the document + }, + "context": "The actual text content of the document", + "distance": 0.95 // Similarity score + } +] +``` + +## التضمين الافتراضي + +بشكل افتراضي، تستخدم الأداة نموذج `text-embedding-3-large` من OpenAI للتحويل إلى متجهات. يتطلب ذلك: +- تعيين مفتاح OpenAI API في البيئة: `OPENAI_API_KEY` + +## التضمينات المخصصة + +بدلاً من استخدام نموذج التضمين الافتراضي، قد ترغب في استخدام دالة تضمين خاصة بك في الحالات التالية: + +1. تريد استخدام نموذج تضمين مختلف (مثل Cohere أو HuggingFace أو نماذج Ollama) +2. تحتاج إلى تقليل التكاليف باستخدام نماذج تضمين مفتوحة المصدر +3. لديك متطلبات محددة لأبعاد المتجهات أو جودة التضمين +4. تريد استخدام تضمينات خاصة بمجال معين (مثل النصوص الطبية أو القانونية) + +إليك مثال باستخدام نموذج HuggingFace: + +```python +from transformers import AutoTokenizer, AutoModel +import torch + +# Load model and tokenizer +tokenizer = AutoTokenizer.from_pretrained('sentence-transformers/all-MiniLM-L6-v2') +model = AutoModel.from_pretrained('sentence-transformers/all-MiniLM-L6-v2') + +def custom_embeddings(text: str) -> list[float]: + # Tokenize and get model outputs + inputs = tokenizer(text, return_tensors="pt", padding=True, truncation=True) + outputs = model(**inputs) + + # Use mean pooling to get text embedding + embeddings = outputs.last_hidden_state.mean(dim=1) + + # Convert to list of floats and return + return embeddings[0].tolist() + +# Use custom embeddings with the tool +from crewai_tools import QdrantConfig + +tool = QdrantVectorSearchTool( + qdrant_config=QdrantConfig( + qdrant_url="your_url", + qdrant_api_key="your_key", + collection_name="your_collection" + ), + custom_embedding_fn=custom_embeddings # Pass your custom function +) +``` + +## معالجة الأخطاء + +تتعامل الأداة مع هذه الأخطاء المحددة: +- تُثير ImportError إذا لم يكن `qdrant-client` مثبتاً (مع خيار التثبيت التلقائي) +- تُثير ValueError إذا لم يتم تعيين `QDRANT_URL` +- تطلب تثبيت `qdrant-client` إذا كان مفقوداً باستخدام `uv add qdrant-client` + +## متغيرات البيئة + +متغيرات البيئة المطلوبة: +```bash +export QDRANT_URL="your_qdrant_url" # If not provided in constructor +export QDRANT_API_KEY="your_api_key" # If not provided in constructor +export OPENAI_API_KEY="your_openai_key" # If using default embeddings +``` diff --git a/docs/ar/tools/database-data/singlestoresearchtool.mdx b/docs/ar/tools/database-data/singlestoresearchtool.mdx new file mode 100644 index 000000000..68c882b6a --- /dev/null +++ b/docs/ar/tools/database-data/singlestoresearchtool.mdx @@ -0,0 +1,60 @@ +--- +title: أداة بحث SingleStore +description: تنفذ `SingleStoreSearchTool` استعلامات SELECT/SHOW بأمان على SingleStore مع تجميع الاتصالات. +icon: circle +mode: "wide" +--- + +# `SingleStoreSearchTool` + +## الوصف + +تنفيذ استعلامات القراءة فقط (`SELECT`/`SHOW`) على SingleStore مع تجميع الاتصالات والتحقق من صحة المدخلات. + +## التثبيت + +```shell +uv add crewai-tools[singlestore] +``` + +## متغيرات البيئة + +يمكن استخدام متغيرات مثل `SINGLESTOREDB_HOST` و `SINGLESTOREDB_USER` و `SINGLESTOREDB_PASSWORD` وغيرها، أو `SINGLESTOREDB_URL` كعنوان DSN واحد. + +قم بتوليد مفتاح API من لوحة تحكم SingleStore، [الوثائق هنا](https://docs.singlestore.com/cloud/reference/management-api/#generate-an-api-key). + +## مثال + +```python Code +from crewai import Agent, Task, Crew +from crewai_tools import SingleStoreSearchTool + +tool = SingleStoreSearchTool( + tables=["products"], + host="host", + user="user", + password="pass", + database="db", +) + +agent = Agent( + role="Analyst", + goal="Query SingleStore", + tools=[tool], + verbose=True, +) + +task = Task( + description="List 5 products", + expected_output="5 rows as JSON/text", + agent=agent, +) + +crew = Crew( + agents=[agent], + tasks=[task], + verbose=True, +) + +result = crew.kickoff() +``` diff --git a/docs/ar/tools/database-data/snowflakesearchtool.mdx b/docs/ar/tools/database-data/snowflakesearchtool.mdx new file mode 100644 index 000000000..ea7e19127 --- /dev/null +++ b/docs/ar/tools/database-data/snowflakesearchtool.mdx @@ -0,0 +1,203 @@ +--- +title: أداة بحث Snowflake +description: تتيح `SnowflakeSearchTool` لوكلاء CrewAI تنفيذ استعلامات SQL وإجراء بحث دلالي على مستودعات بيانات Snowflake. +icon: snowflake +mode: "wide" +--- + +# `SnowflakeSearchTool` + +## الوصف + +صُممت `SnowflakeSearchTool` للاتصال بمستودعات بيانات Snowflake وتنفيذ استعلامات SQL مع ميزات متقدمة مثل تجميع الاتصالات ومنطق إعادة المحاولة والتنفيذ غير المتزامن. تتيح هذه الأداة لوكلاء CrewAI التفاعل مع قواعد بيانات Snowflake، مما يجعلها مثالية لمهام تحليل البيانات وإعداد التقارير وذكاء الأعمال التي تتطلب الوصول إلى بيانات المؤسسة المخزنة في Snowflake. + +## التثبيت + +لاستخدام هذه الأداة، تحتاج إلى تثبيت التبعيات المطلوبة: + +```shell +uv add cryptography snowflake-connector-python snowflake-sqlalchemy +``` + +أو بدلاً من ذلك: + +```shell +uv sync --extra snowflake +``` + +## خطوات البدء + +لاستخدام `SnowflakeSearchTool` بفعالية، اتبع هذه الخطوات: + +1. **تثبيت التبعيات**: قم بتثبيت الحزم المطلوبة باستخدام أحد الأوامر أعلاه. +2. **تكوين اتصال Snowflake**: أنشئ كائن `SnowflakeConfig` ببيانات اعتماد Snowflake الخاصة بك. +3. **تهيئة الأداة**: أنشئ نسخة من الأداة بالتكوين اللازم. +4. **تنفيذ الاستعلامات**: استخدم الأداة لتشغيل استعلامات SQL على قاعدة بيانات Snowflake الخاصة بك. + +## مثال + +يوضح المثال التالي كيفية استخدام `SnowflakeSearchTool` للاستعلام عن البيانات من قاعدة بيانات Snowflake: + +```python Code +from crewai import Agent, Task, Crew +from crewai_tools import SnowflakeSearchTool, SnowflakeConfig + +# Create Snowflake configuration +config = SnowflakeConfig( + account="your_account", + user="your_username", + password="your_password", + warehouse="COMPUTE_WH", + database="your_database", + snowflake_schema="your_schema" +) + +# Initialize the tool +snowflake_tool = SnowflakeSearchTool(config=config) + +# Define an agent that uses the tool +data_analyst_agent = Agent( + role="Data Analyst", + goal="Analyze data from Snowflake database", + backstory="An expert data analyst who can extract insights from enterprise data.", + tools=[snowflake_tool], + verbose=True, +) + +# Example task to query sales data +query_task = Task( + description="Query the sales data for the last quarter and summarize the top 5 products by revenue.", + expected_output="A summary of the top 5 products by revenue for the last quarter.", + agent=data_analyst_agent, +) + +# Create and run the crew +crew = Crew(agents=[data_analyst_agent], + tasks=[query_task]) +result = crew.kickoff() +``` + +يمكنك أيضاً تخصيص الأداة بمعاملات إضافية: + +```python Code +# Initialize the tool with custom parameters +snowflake_tool = SnowflakeSearchTool( + config=config, + pool_size=10, + max_retries=5, + retry_delay=2.0, + enable_caching=True +) +``` + +## المعاملات + +### معاملات SnowflakeConfig + +يقبل صنف `SnowflakeConfig` المعاملات التالية: + +- **account**: مطلوب. معرّف حساب Snowflake. +- **user**: مطلوب. اسم مستخدم Snowflake. +- **password**: اختياري*. كلمة مرور Snowflake. +- **private_key_path**: اختياري*. مسار ملف المفتاح الخاص (بديل لكلمة المرور). +- **warehouse**: مطلوب. اسم مستودع Snowflake. +- **database**: مطلوب. قاعدة البيانات الافتراضية. +- **snowflake_schema**: مطلوب. المخطط الافتراضي. +- **role**: اختياري. دور Snowflake. +- **session_parameters**: اختياري. معاملات جلسة مخصصة كقاموس. + +*يجب توفير إما `password` أو `private_key_path`. + +### معاملات SnowflakeSearchTool + +تقبل `SnowflakeSearchTool` المعاملات التالية أثناء التهيئة: + +- **config**: مطلوب. كائن `SnowflakeConfig` يحتوي على تفاصيل الاتصال. +- **pool_size**: اختياري. عدد الاتصالات في المجمع. الافتراضي هو 5. +- **max_retries**: اختياري. الحد الأقصى لمحاولات إعادة المحاولة للاستعلامات الفاشلة. الافتراضي هو 3. +- **retry_delay**: اختياري. التأخير بين المحاولات بالثواني. الافتراضي هو 1.0. +- **enable_caching**: اختياري. ما إذا كان سيتم تفعيل التخزين المؤقت لنتائج الاستعلامات. الافتراضي هو True. + +## الاستخدام + +عند استخدام `SnowflakeSearchTool`، تحتاج إلى توفير المعاملات التالية: + +- **query**: مطلوب. استعلام SQL المراد تنفيذه. +- **database**: اختياري. تجاوز قاعدة البيانات الافتراضية المحددة في التكوين. +- **snowflake_schema**: اختياري. تجاوز المخطط الافتراضي المحدد في التكوين. +- **timeout**: اختياري. مهلة الاستعلام بالثواني. الافتراضي هو 300. + +ستُرجع الأداة نتائج الاستعلام كقائمة من القواميس، حيث يمثل كل قاموس صفاً بأسماء الأعمدة كمفاتيح. + +```python Code +# Example of using the tool with an agent +data_analyst = Agent( + role="Data Analyst", + goal="Analyze sales data from Snowflake", + backstory="An expert data analyst with experience in SQL and data visualization.", + tools=[snowflake_tool], + verbose=True +) + +# The agent will use the tool with parameters like: +# query="SELECT product_name, SUM(revenue) as total_revenue FROM sales GROUP BY product_name ORDER BY total_revenue DESC LIMIT 5" +# timeout=600 + +# Create a task for the agent +analysis_task = Task( + description="Query the sales database and identify the top 5 products by revenue for the last quarter.", + expected_output="A detailed analysis of the top 5 products by revenue.", + agent=data_analyst +) + +# Run the task +crew = Crew( + agents=[data_analyst], + tasks=[analysis_task] +) +result = crew.kickoff() +``` + +## الميزات المتقدمة + +### تجميع الاتصالات + +تُطبّق `SnowflakeSearchTool` تجميع الاتصالات لتحسين الأداء من خلال إعادة استخدام اتصالات قاعدة البيانات. يمكنك التحكم في حجم المجمع بمعامل `pool_size`. + +### إعادة المحاولة التلقائية + +تُعيد الأداة تلقائياً محاولة الاستعلامات الفاشلة مع تراجع أسي. يمكنك تكوين سلوك إعادة المحاولة بمعاملات `max_retries` و `retry_delay`. + +### التخزين المؤقت لنتائج الاستعلامات + +لتحسين أداء الاستعلامات المتكررة، يمكن للأداة تخزين نتائج الاستعلامات مؤقتاً. هذه الميزة مفعّلة افتراضياً ولكن يمكن تعطيلها بتعيين `enable_caching=False`. + +### مصادقة زوج المفاتيح + +بالإضافة إلى مصادقة كلمة المرور، تدعم الأداة مصادقة زوج المفاتيح لتعزيز الأمان: + +```python Code +config = SnowflakeConfig( + account="your_account", + user="your_username", + private_key_path="/path/to/your/private/key.p8", + warehouse="COMPUTE_WH", + database="your_database", + snowflake_schema="your_schema" +) +``` + +## معالجة الأخطاء + +تتضمن `SnowflakeSearchTool` معالجة شاملة للأخطاء لمشكلات Snowflake الشائعة: + +- فشل الاتصال +- انتهاء مهلة الاستعلام +- أخطاء المصادقة +- أخطاء قاعدة البيانات والمخطط + +عند حدوث خطأ، ستحاول الأداة إعادة العملية (إذا تم تكوينها) وتوفير معلومات تفصيلية عن الخطأ. + +## الخلاصة + +توفر `SnowflakeSearchTool` طريقة قوية لدمج مستودعات بيانات Snowflake مع وكلاء CrewAI. مع ميزات مثل تجميع الاتصالات وإعادة المحاولة التلقائية والتخزين المؤقت للاستعلامات، تتيح وصولاً فعالاً وموثوقاً لبيانات المؤسسة. هذه الأداة مفيدة بشكل خاص لمهام تحليل البيانات وإعداد التقارير وذكاء الأعمال التي تتطلب الوصول إلى بيانات منظمة مخزنة في Snowflake. diff --git a/docs/ar/tools/database-data/weaviatevectorsearchtool.mdx b/docs/ar/tools/database-data/weaviatevectorsearchtool.mdx new file mode 100644 index 000000000..8579ccafc --- /dev/null +++ b/docs/ar/tools/database-data/weaviatevectorsearchtool.mdx @@ -0,0 +1,168 @@ +--- +title: بحث متجهي Weaviate +description: أداة `WeaviateVectorSearchTool` مصممة للبحث في قاعدة بيانات Weaviate المتجهية عن مستندات متشابهة دلالياً باستخدام البحث الهجين. +icon: network-wired +mode: "wide" +--- + +## نظرة عامة + +صُممت `WeaviateVectorSearchTool` خصيصاً لإجراء عمليات بحث دلالي داخل المستندات المخزنة في قاعدة بيانات Weaviate المتجهية. تتيح لك هذه الأداة العثور على مستندات متشابهة دلالياً لاستعلام معين، من خلال الاستفادة من قوة البحث المتجهي والبحث بالكلمات المفتاحية للحصول على نتائج بحث أكثر دقة وذات صلة بالسياق. + +[Weaviate](https://weaviate.io/) هي قاعدة بيانات متجهية تخزن وتستعلم عن التضمينات المتجهية، مما يتيح إمكانيات البحث الدلالي. + +## التثبيت + +لدمج هذه الأداة في مشروعك، تحتاج إلى تثبيت عميل Weaviate: + +```shell +uv add weaviate-client +``` + +## خطوات البدء + +لاستخدام `WeaviateVectorSearchTool` بفعالية، اتبع هذه الخطوات: + +1. **تثبيت الحزمة**: تأكد من تثبيت حزمتي `crewai[tools]` و `weaviate-client` في بيئة Python الخاصة بك. +2. **إعداد Weaviate**: قم بإعداد مجموعة Weaviate. يمكنك اتباع [وثائق Weaviate](https://weaviate.io/developers/wcs/manage-clusters/connect) للتعليمات. +3. **مفاتيح API**: احصل على عنوان URL لمجموعة Weaviate ومفتاح API. +4. **مفتاح OpenAI API**: تأكد من تعيين مفتاح OpenAI API في متغيرات البيئة كـ `OPENAI_API_KEY`. + +## مثال + +يوضح المثال التالي كيفية تهيئة الأداة وتنفيذ بحث: + +```python Code +from crewai_tools import WeaviateVectorSearchTool + +# Initialize the tool +tool = WeaviateVectorSearchTool( + collection_name='example_collections', + limit=3, + alpha=0.75, + weaviate_cluster_url="https://your-weaviate-cluster-url.com", + weaviate_api_key="your-weaviate-api-key", +) + +@agent +def search_agent(self) -> Agent: + ''' + This agent uses the WeaviateVectorSearchTool to search for + semantically similar documents in a Weaviate vector database. + ''' + return Agent( + config=self.agents_config["search_agent"], + tools=[tool] + ) +``` + +## المعاملات + +تقبل `WeaviateVectorSearchTool` المعاملات التالية: + +- **collection_name**: مطلوب. اسم المجموعة المراد البحث فيها. +- **weaviate_cluster_url**: مطلوب. عنوان URL لمجموعة Weaviate. +- **weaviate_api_key**: مطلوب. مفتاح API لمجموعة Weaviate. +- **limit**: اختياري. عدد النتائج المُرجعة. الافتراضي هو `3`. +- **alpha**: اختياري. يتحكم في الترجيح بين البحث المتجهي والبحث بالكلمات المفتاحية (BM25). alpha = 0 -> BM25 فقط، alpha = 1 -> بحث متجهي فقط. الافتراضي هو `0.75`. +- **vectorizer**: اختياري. المحوّل المتجهي المستخدم. إذا لم يُحدد، سيستخدم `text2vec_openai` مع نموذج `nomic-embed-text`. +- **generative_model**: اختياري. النموذج التوليدي المستخدم. إذا لم يُحدد، سيستخدم `gpt-4o` من OpenAI. + +## التكوين المتقدم + +يمكنك تخصيص المحوّل المتجهي والنموذج التوليدي المستخدمين في الأداة: + +```python Code +from crewai_tools import WeaviateVectorSearchTool +from weaviate.classes.config import Configure + +# Setup custom model for vectorizer and generative model +tool = WeaviateVectorSearchTool( + collection_name='example_collections', + limit=3, + alpha=0.75, + vectorizer=Configure.Vectorizer.text2vec_openai(model="nomic-embed-text"), + generative_model=Configure.Generative.openai(model="gpt-4o-mini"), + weaviate_cluster_url="https://your-weaviate-cluster-url.com", + weaviate_api_key="your-weaviate-api-key", +) +``` + +## تحميل المستندات مسبقاً + +يمكنك تحميل قاعدة بيانات Weaviate بالمستندات مسبقاً قبل استخدام الأداة: + +```python Code +import os +from crewai_tools import WeaviateVectorSearchTool +import weaviate +from weaviate.classes.init import Auth + +# Connect to Weaviate +client = weaviate.connect_to_weaviate_cloud( + cluster_url="https://your-weaviate-cluster-url.com", + auth_credentials=Auth.api_key("your-weaviate-api-key"), + headers={"X-OpenAI-Api-Key": "your-openai-api-key"} +) + +# Get or create collection +test_docs = client.collections.get("example_collections") +if not test_docs: + test_docs = client.collections.create( + name="example_collections", + vectorizer_config=Configure.Vectorizer.text2vec_openai(model="nomic-embed-text"), + generative_config=Configure.Generative.openai(model="gpt-4o"), + ) + +# Load documents +docs_to_load = os.listdir("knowledge") +with test_docs.batch.dynamic() as batch: + for d in docs_to_load: + with open(os.path.join("knowledge", d), "r") as f: + content = f.read() + batch.add_object( + { + "content": content, + "year": d.split("_")[0], + } + ) + +# Initialize the tool +tool = WeaviateVectorSearchTool( + collection_name='example_collections', + limit=3, + alpha=0.75, + weaviate_cluster_url="https://your-weaviate-cluster-url.com", + weaviate_api_key="your-weaviate-api-key", +) +``` + +## مثال على التكامل مع الوكيل + +إليك كيفية دمج `WeaviateVectorSearchTool` مع وكيل CrewAI: + +```python Code +from crewai import Agent +from crewai_tools import WeaviateVectorSearchTool + +# Initialize the tool +weaviate_tool = WeaviateVectorSearchTool( + collection_name='example_collections', + limit=3, + alpha=0.75, + weaviate_cluster_url="https://your-weaviate-cluster-url.com", + weaviate_api_key="your-weaviate-api-key", +) + +# Create an agent with the tool +rag_agent = Agent( + name="rag_agent", + role="You are a helpful assistant that can answer questions with the help of the WeaviateVectorSearchTool.", + llm="gpt-4o-mini", + tools=[weaviate_tool], +) +``` + +## الخلاصة + +توفر `WeaviateVectorSearchTool` طريقة قوية للبحث عن مستندات متشابهة دلالياً في قاعدة بيانات Weaviate المتجهية. من خلال الاستفادة من التضمينات المتجهية، تتيح نتائج بحث أكثر دقة وذات صلة بالسياق مقارنة بعمليات البحث التقليدية القائمة على الكلمات المفتاحية. هذه الأداة مفيدة بشكل خاص للتطبيقات التي تتطلب العثور على المعلومات بناءً على المعنى بدلاً من التطابق الحرفي. diff --git a/docs/ar/tools/file-document/csvsearchtool.mdx b/docs/ar/tools/file-document/csvsearchtool.mdx new file mode 100644 index 000000000..f9d5d7bf8 --- /dev/null +++ b/docs/ar/tools/file-document/csvsearchtool.mdx @@ -0,0 +1,76 @@ +--- +title: بحث RAG في CSV +description: أداة `CSVSearchTool` هي أداة RAG (الاسترجاع المعزز بالتوليد) قوية مصممة لعمليات البحث الدلالي داخل محتوى ملف CSV. +icon: file-csv +mode: "wide" +--- + +# `CSVSearchTool` + + + **تجريبية**: لا نزال نعمل على تحسين الأدوات، لذا قد يحدث سلوك غير متوقع أو تغييرات في المستقبل. + + +## الوصف + +تُستخدم هذه الأداة لإجراء بحث RAG (الاسترجاع المعزز بالتوليد) داخل محتوى ملف CSV. تتيح للمستخدمين البحث دلالياً عن استعلامات في محتوى ملف CSV محدد. هذه الميزة مفيدة بشكل خاص لاستخراج المعلومات من مجموعات بيانات CSV الكبيرة حيث قد تكون طرق البحث التقليدية غير فعالة. جميع الأدوات التي تحتوي على "Search" في اسمها، بما في ذلك CSVSearchTool، هي أدوات RAG مصممة للبحث في مصادر بيانات مختلفة. + +## التثبيت + +قم بتثبيت حزمة crewai_tools + +```shell +pip install 'crewai[tools]' +``` + +## مثال + +```python Code +from crewai_tools import CSVSearchTool + +# Initialize the tool with a specific CSV file. +# This setup allows the agent to only search the given CSV file. +tool = CSVSearchTool(csv='path/to/your/csvfile.csv') + +# OR + +# Initialize the tool without a specific CSV file. +# Agent will need to provide the CSV path at runtime. +tool = CSVSearchTool() +``` + +## المعاملات + +يمكن استخدام المعاملات التالية لتخصيص سلوك `CSVSearchTool`: + +| المعامل | النوع | الوصف | +|:---------------|:---------|:-------------------------------------------------------------------------------------------------------------------------------------| +| **csv** | `string` | _اختياري_. مسار ملف CSV المراد البحث فيه. هذا معامل إلزامي إذا تمت تهيئة الأداة بدون ملف CSV محدد؛ وإلا فهو اختياري. | + +## النموذج والتضمينات المخصصة + +بشكل افتراضي، تستخدم الأداة OpenAI لكل من التضمينات والتلخيص. لتخصيص النموذج، يمكنك استخدام قاموس تكوين كما يلي: + +```python Code +from chromadb.config import Settings + +tool = CSVSearchTool( + config={ + "embedding_model": { + "provider": "openai", + "config": { + "model": "text-embedding-3-small", + # "api_key": "sk-...", + }, + }, + "vectordb": { + "provider": "chromadb", # or "qdrant" + "config": { + # "settings": Settings(persist_directory="/content/chroma", allow_reset=True, is_persistent=True), + # from qdrant_client.models import VectorParams, Distance + # "vectors_config": VectorParams(size=384, distance=Distance.COSINE), + } + }, + } +) +``` diff --git a/docs/ar/tools/file-document/directoryreadtool.mdx b/docs/ar/tools/file-document/directoryreadtool.mdx new file mode 100644 index 000000000..1e9d7ddee --- /dev/null +++ b/docs/ar/tools/file-document/directoryreadtool.mdx @@ -0,0 +1,52 @@ +--- +title: قراءة المجلدات +description: أداة `DirectoryReadTool` هي أداة مساعدة قوية مصممة لتوفير قائمة شاملة بمحتويات المجلد. +icon: folder-tree +mode: "wide" +--- + +# `DirectoryReadTool` + + + لا نزال نعمل على تحسين الأدوات، لذا قد يحدث سلوك غير متوقع أو تغييرات في المستقبل. + + +## الوصف + +أداة DirectoryReadTool هي أداة مساعدة قوية مصممة لتوفير قائمة شاملة بمحتويات المجلد. يمكنها التنقل بشكل متكرر عبر المجلد المحدد، مما يوفر للمستخدمين تعداداً مفصلاً لجميع الملفات، بما في ذلك تلك الموجودة داخل المجلدات الفرعية. هذه الأداة ضرورية للمهام التي تتطلب جرداً شاملاً لهياكل المجلدات أو للتحقق من تنظيم الملفات داخل المجلدات. + +## التثبيت + +لاستخدام DirectoryReadTool في مشروعك، قم بتثبيت حزمة `crewai_tools`. إذا لم تكن هذه الحزمة جزءاً من بيئتك بعد، يمكنك تثبيتها باستخدام pip بالأمر التالي: + +```shell +pip install 'crewai[tools]' +``` + +يُثبّت هذا الأمر أحدث إصدار من حزمة `crewai_tools`، مما يمنح الوصول إلى DirectoryReadTool بالإضافة إلى أدوات مساعدة أخرى. + +## مثال + +استخدام DirectoryReadTool بسيط ومباشر. يوضح مقتطف الكود التالي كيفية إعدادها واستخدام الأداة لعرض محتويات مجلد محدد: + +```python Code +from crewai_tools import DirectoryReadTool + +# Initialize the tool so the agent can read any directory's content +# it learns about during execution +tool = DirectoryReadTool() + +# OR + +# Initialize the tool with a specific directory, +# so the agent can only read the content of the specified directory +tool = DirectoryReadTool(directory='/path/to/your/directory') +``` + +## المعاملات + +يمكن استخدام المعاملات التالية لتخصيص سلوك `DirectoryReadTool`: + +| المعامل | النوع | الوصف | +|:---------------|:---------|:-------------------------------------------------------------------------------------------------------------------------------------| +| **directory** | `string` | _اختياري_. معامل يحدد المسار إلى المجلد الذي ترغب في عرض محتوياته. يقبل كلاً من المسارات المطلقة والنسبية، ويوجه الأداة إلى المجلد المطلوب لعرض المحتوى. | diff --git a/docs/ar/tools/file-document/directorysearchtool.mdx b/docs/ar/tools/file-document/directorysearchtool.mdx new file mode 100644 index 000000000..2e5595865 --- /dev/null +++ b/docs/ar/tools/file-document/directorysearchtool.mdx @@ -0,0 +1,70 @@ +--- +title: بحث RAG في المجلدات +description: أداة `DirectorySearchTool` هي أداة RAG (الاسترجاع المعزز بالتوليد) قوية مصممة لعمليات البحث الدلالي داخل محتوى المجلد. +icon: address-book +mode: "wide" +--- + +# `DirectorySearchTool` + + + **تجريبية**: أداة DirectorySearchTool قيد التطوير المستمر. قد تُضاف ميزات أو تُزال، وقد يتغير الأداء بشكل غير متوقع أثناء تحسين الأداة. + + +## الوصف + +تتيح DirectorySearchTool البحث الدلالي داخل محتوى المجلدات المحددة، مستفيدة من منهجية الاسترجاع المعزز بالتوليد (RAG) للتنقل الفعال بين الملفات. صُممت لتكون مرنة، حيث تسمح للمستخدمين بتحديد مجلدات البحث ديناميكياً أثناء التشغيل أو تعيين مجلد ثابت أثناء الإعداد الأولي. + +## التثبيت + +لاستخدام DirectorySearchTool، ابدأ بتثبيت حزمة crewai_tools. نفّذ الأمر التالي في الطرفية: + +```shell +pip install 'crewai[tools]' +``` + +## التهيئة والاستخدام + +قم باستيراد DirectorySearchTool من حزمة `crewai_tools` للبدء. يمكنك تهيئة الأداة بدون تحديد مجلد، مما يتيح تعيين مجلد البحث أثناء التشغيل. بدلاً من ذلك، يمكن تهيئة الأداة بمجلد محدد مسبقاً. + +```python Code +from crewai_tools import DirectorySearchTool + +# For dynamic directory specification at runtime +tool = DirectorySearchTool() + +# For fixed directory searches +tool = DirectorySearchTool(directory='/path/to/directory') +``` + +## المعاملات + +- `directory`: معامل نصي يحدد مجلد البحث. هذا اختياري أثناء التهيئة لكنه مطلوب لعمليات البحث إذا لم يتم تعيينه مبدئياً. + +## النموذج والتضمينات المخصصة + +تستخدم DirectorySearchTool افتراضياً OpenAI للتضمينات والتلخيص. تتضمن خيارات التخصيص لهذه الإعدادات تغيير مزود النموذج والتكوين، مما يعزز المرونة للمستخدمين المتقدمين. + +```python Code +from chromadb.config import Settings + +tool = DirectorySearchTool( + config={ + "embedding_model": { + "provider": "openai", + "config": { + "model": "text-embedding-3-small", + # "api_key": "sk-...", + }, + }, + "vectordb": { + "provider": "chromadb", # or "qdrant" + "config": { + # "settings": Settings(persist_directory="/content/chroma", allow_reset=True, is_persistent=True), + # from qdrant_client.models import VectorParams, Distance + # "vectors_config": VectorParams(size=384, distance=Distance.COSINE), + } + }, + } +) +``` diff --git a/docs/ar/tools/file-document/docxsearchtool.mdx b/docs/ar/tools/file-document/docxsearchtool.mdx new file mode 100644 index 000000000..046941bc1 --- /dev/null +++ b/docs/ar/tools/file-document/docxsearchtool.mdx @@ -0,0 +1,77 @@ +--- +title: بحث RAG في DOCX +description: أداة `DOCXSearchTool` هي أداة RAG مصممة للبحث الدلالي داخل مستندات DOCX. +icon: file-word +mode: "wide" +--- + +# `DOCXSearchTool` + + + لا نزال نعمل على تحسين الأدوات، لذا قد يحدث سلوك غير متوقع أو تغييرات في المستقبل. + + +## الوصف + +أداة `DOCXSearchTool` هي أداة RAG مصممة للبحث الدلالي داخل مستندات DOCX. تتيح للمستخدمين البحث بفعالية واستخراج المعلومات ذات الصلة من ملفات DOCX باستخدام عمليات بحث قائمة على الاستعلامات. هذه الأداة لا تُقدَّر بثمن لمهام تحليل البيانات وإدارة المعلومات والبحث، حيث تبسط عملية العثور على معلومات محددة داخل مجموعات مستندات كبيرة. + +## التثبيت + +قم بتثبيت حزمة crewai_tools بتنفيذ الأمر التالي في الطرفية: + +```shell +uv pip install docx2txt 'crewai[tools]' +``` + +## مثال + +يوضح المثال التالي تهيئة DOCXSearchTool للبحث داخل محتوى أي ملف DOCX أو بمسار ملف DOCX محدد. + +```python Code +from crewai_tools import DOCXSearchTool + +# Initialize the tool to search within any DOCX file's content +tool = DOCXSearchTool() + +# OR + +# Initialize the tool with a specific DOCX file, +# so the agent can only search the content of the specified DOCX file +tool = DOCXSearchTool(docx='path/to/your/document.docx') +``` + +## المعاملات + +يمكن استخدام المعاملات التالية لتخصيص سلوك `DOCXSearchTool`: + +| المعامل | النوع | الوصف | +|:---------------|:---------|:-------------------------------------------------------------------------------------------------------------------------------------| +| **docx** | `string` | _اختياري_. معامل يحدد مسار ملف DOCX المراد البحث فيه. إذا لم يُقدَّم أثناء التهيئة، تسمح الأداة بتحديد مسار محتوى أي ملف DOCX للبحث لاحقاً. | + +## النموذج والتضمينات المخصصة + +بشكل افتراضي، تستخدم الأداة OpenAI لكل من التضمينات والتلخيص. لتخصيص النموذج، يمكنك استخدام قاموس تكوين كما يلي: + +```python Code +from chromadb.config import Settings + +tool = DOCXSearchTool( + config={ + "embedding_model": { + "provider": "openai", + "config": { + "model": "text-embedding-3-small", + # "api_key": "sk-...", + }, + }, + "vectordb": { + "provider": "chromadb", # or "qdrant" + "config": { + # "settings": Settings(persist_directory="/content/chroma", allow_reset=True, is_persistent=True), + # from qdrant_client.models import VectorParams, Distance + # "vectors_config": VectorParams(size=384, distance=Distance.COSINE), + } + }, + } +) +``` diff --git a/docs/ar/tools/file-document/filereadtool.mdx b/docs/ar/tools/file-document/filereadtool.mdx new file mode 100644 index 000000000..10053a735 --- /dev/null +++ b/docs/ar/tools/file-document/filereadtool.mdx @@ -0,0 +1,42 @@ +--- +title: قراءة الملفات +description: أداة `FileReadTool` مصممة لقراءة الملفات من نظام الملفات المحلي. +icon: folders +mode: "wide" +--- + +## نظرة عامة + + + لا نزال نعمل على تحسين الأدوات، لذا قد يحدث سلوك غير متوقع أو تغييرات في المستقبل. + + +تمثل أداة FileReadTool مفهومياً مجموعة من الوظائف ضمن حزمة crewai_tools تهدف إلى تسهيل قراءة الملفات واسترجاع المحتوى. تتضمن هذه المجموعة أدوات لمعالجة ملفات نصية دفعية، وقراءة ملفات التكوين أثناء التشغيل، واستيراد البيانات للتحليلات. تدعم مجموعة متنوعة من صيغ الملفات النصية مثل `.txt` و `.csv` و `.json` وغيرها. اعتماداً على نوع الملف، توفر المجموعة وظائف متخصصة، مثل تحويل محتوى JSON إلى قاموس Python لسهولة الاستخدام. + +## التثبيت + +لاستخدام الوظائف المنسوبة سابقاً لأداة FileReadTool، قم بتثبيت حزمة crewai_tools: + +```shell +pip install 'crewai[tools]' +``` + +## مثال على الاستخدام + +للبدء مع FileReadTool: + +```python Code +from crewai_tools import FileReadTool + +# Initialize the tool to read any files the agents knows or lean the path for +file_read_tool = FileReadTool() + +# OR + +# Initialize the tool with a specific file path, so the agent can only read the content of the specified file +file_read_tool = FileReadTool(file_path='path/to/your/file.txt') +``` + +## المعاملات + +- `file_path`: مسار الملف المراد قراءته. يقبل كلاً من المسارات المطلقة والنسبية. تأكد من وجود الملف وأن لديك الصلاحيات اللازمة للوصول إليه. diff --git a/docs/ar/tools/file-document/filewritetool.mdx b/docs/ar/tools/file-document/filewritetool.mdx new file mode 100644 index 000000000..fc01a9c0a --- /dev/null +++ b/docs/ar/tools/file-document/filewritetool.mdx @@ -0,0 +1,47 @@ +--- +title: كتابة الملفات +description: أداة `FileWriterTool` مصممة لكتابة المحتوى في الملفات. +icon: file-pen +mode: "wide" +--- + +# `FileWriterTool` + +## الوصف + +أداة `FileWriterTool` هي مكوّن من حزمة crewai_tools، مصممة لتبسيط عملية كتابة المحتوى في الملفات مع توافق عبر المنصات (Windows و Linux و macOS). تكون مفيدة بشكل خاص في سيناريوهات مثل توليد التقارير وحفظ السجلات وإنشاء ملفات التكوين والمزيد. تتعامل هذه الأداة مع اختلافات المسارات عبر أنظمة التشغيل، وتدعم ترميز UTF-8، وتنشئ المجلدات تلقائياً إذا لم تكن موجودة، مما يسهل تنظيم المخرجات بشكل موثوق عبر المنصات المختلفة. + +## التثبيت + +قم بتثبيت حزمة crewai_tools لاستخدام `FileWriterTool` في مشاريعك: + +```shell +pip install 'crewai[tools]' +``` + +## مثال + +للبدء مع `FileWriterTool`: + +```python Code +from crewai_tools import FileWriterTool + +# Initialize the tool +file_writer_tool = FileWriterTool() + +# Write content to a file in a specified directory +result = file_writer_tool._run('example.txt', 'This is a test content.', 'test_directory') +print(result) +``` + +## المعاملات + +- `filename`: اسم الملف الذي تريد إنشاءه أو الكتابة فوقه. +- `content`: المحتوى المراد كتابته في الملف. +- `directory` (اختياري): مسار المجلد حيث سيتم إنشاء الملف. الافتراضي هو المجلد الحالي (`.`). إذا لم يكن المجلد موجوداً، سيتم إنشاؤه. + +## الخلاصة + +من خلال دمج `FileWriterTool` في أطقمك، يمكن للوكلاء كتابة المحتوى في الملفات بشكل موثوق عبر أنظمة التشغيل المختلفة. هذه الأداة ضرورية للمهام التي تتطلب حفظ بيانات المخرجات وإنشاء أنظمة ملفات منظمة والتعامل مع عمليات الملفات عبر المنصات. يُوصى بها بشكل خاص لمستخدمي Windows الذين قد يواجهون مشكلات في كتابة الملفات مع عمليات ملفات Python القياسية. + +من خلال الالتزام بإرشادات الإعداد والاستخدام المقدمة، فإن دمج هذه الأداة في المشاريع أمر مباشر ويضمن سلوكاً متسقاً لكتابة الملفات عبر جميع المنصات. diff --git a/docs/ar/tools/file-document/jsonsearchtool.mdx b/docs/ar/tools/file-document/jsonsearchtool.mdx new file mode 100644 index 000000000..62ef99081 --- /dev/null +++ b/docs/ar/tools/file-document/jsonsearchtool.mdx @@ -0,0 +1,75 @@ +--- +title: بحث RAG في JSON +description: أداة `JSONSearchTool` مصممة للبحث في ملفات JSON وإرجاع النتائج الأكثر صلة. +icon: file-code +mode: "wide" +--- + +# `JSONSearchTool` + + + أداة JSONSearchTool حالياً في مرحلة تجريبية. هذا يعني أن الأداة قيد التطوير + النشط، وقد يواجه المستخدمون سلوكاً غير متوقع أو تغييرات. نشجع بشدة التعليقات + حول أي مشكلات أو اقتراحات للتحسين. + + +## الوصف + +صُممت أداة JSONSearchTool لتسهيل عمليات البحث الفعالة والدقيقة داخل محتوى ملفات JSON. تستخدم آلية بحث RAG (الاسترجاع والتوليد)، مما يتيح للمستخدمين تحديد مسار JSON لعمليات بحث مستهدفة داخل ملف JSON معين. تحسّن هذه القدرة بشكل ملحوظ دقة نتائج البحث وصلتها. + +## التثبيت + +لتثبيت JSONSearchTool، استخدم أمر pip التالي: + +```shell +pip install 'crewai[tools]' +``` + +## أمثلة على الاستخدام + +فيما يلي أمثلة محدّثة حول كيفية استخدام JSONSearchTool بفعالية للبحث داخل ملفات JSON. تأخذ هذه الأمثلة بعين الاعتبار التنفيذ الحالي وأنماط الاستخدام المحددة في قاعدة الكود. + +```python Code +from crewai_tools import JSONSearchTool + +# General JSON content search +# This approach is suitable when the JSON path is either known beforehand or can be dynamically identified. +tool = JSONSearchTool() + +# Restricting search to a specific JSON file +# Use this initialization method when you want to limit the search scope to a specific JSON file. +tool = JSONSearchTool(json_path='./path/to/your/file.json') +``` + +## المعاملات + +- `json_path` (str, اختياري): يحدد مسار ملف JSON المراد البحث فيه. هذا المعامل غير مطلوب إذا تمت تهيئة الأداة لبحث عام. عند تقديمه، يقتصر البحث على ملف JSON المحدد. + +## خيارات التكوين + +تدعم أداة JSONSearchTool تخصيصاً واسعاً من خلال قاموس تكوين. يتيح هذا للمستخدمين اختيار نماذج مختلفة للتضمينات والتلخيص بناءً على متطلباتهم. + +```python Code +tool = JSONSearchTool( + config={ + "llm": { + "provider": "ollama", # Other options include google, openai, anthropic, llama2, etc. + "config": { + "model": "llama2", + # Additional optional configurations can be specified here. + # temperature=0.5, + # top_p=1, + # stream=true, + }, + }, + "embedding_model": { + "provider": "google-generativeai", # or openai, ollama, ... + "config": { + "model_name": "gemini-embedding-001", + "task_type": "RETRIEVAL_DOCUMENT", + # Further customization options can be added here. + }, + }, + } +) +``` diff --git a/docs/ar/tools/file-document/mdxsearchtool.mdx b/docs/ar/tools/file-document/mdxsearchtool.mdx new file mode 100644 index 000000000..c70f30d7b --- /dev/null +++ b/docs/ar/tools/file-document/mdxsearchtool.mdx @@ -0,0 +1,72 @@ +--- +title: بحث RAG في MDX +description: أداة `MDXSearchTool` مصممة للبحث في ملفات MDX وإرجاع النتائج الأكثر صلة. +icon: markdown +mode: "wide" +--- + +# `MDXSearchTool` + + + أداة MDXSearchTool في تطوير مستمر. قد تُضاف ميزات أو تُزال، وقد تتغير الوظائف بشكل غير متوقع أثناء تحسين الأداة. + + +## الوصف + +أداة البحث في MDX هي مكوّن من حزمة `crewai_tools` يهدف إلى تسهيل استخراج لغة Markdown المتقدمة. تتيح للمستخدمين البحث بفعالية واستخراج المعلومات ذات الصلة من ملفات MD باستخدام عمليات بحث قائمة على الاستعلامات. هذه الأداة لا تُقدَّر بثمن لمهام تحليل البيانات وإدارة المعلومات والبحث، حيث تبسط عملية العثور على معلومات محددة داخل مجموعات مستندات كبيرة. + +## التثبيت + +قبل استخدام أداة البحث في MDX، تأكد من تثبيت حزمة `crewai_tools`. إذا لم تكن مثبتة، يمكنك تثبيتها بالأمر التالي: + +```shell +pip install 'crewai[tools]' +``` + +## مثال على الاستخدام + +لاستخدام أداة البحث في MDX، يجب أولاً إعداد متغيرات البيئة اللازمة. ثم قم بدمج الأداة في مشروع crewAI الخاص بك لبدء أبحاث السوق. فيما يلي مثال أساسي لكيفية القيام بذلك: + +```python Code +from crewai_tools import MDXSearchTool + +# Initialize the tool to search any MDX content it learns about during execution +tool = MDXSearchTool() + +# OR + +# Initialize the tool with a specific MDX file path for an exclusive search within that document +tool = MDXSearchTool(mdx='path/to/your/document.mdx') +``` + +## المعاملات + +- mdx: **اختياري**. يحدد مسار ملف MDX للبحث. يمكن تقديمه أثناء التهيئة. + +## تخصيص النموذج والتضمينات + +تستخدم الأداة افتراضياً OpenAI للتضمينات والتلخيص. للتخصيص، استخدم قاموس تكوين كما هو موضح أدناه: + +```python Code +from chromadb.config import Settings + +tool = MDXSearchTool( + config={ + "embedding_model": { + "provider": "openai", + "config": { + "model": "text-embedding-3-small", + # "api_key": "sk-...", + }, + }, + "vectordb": { + "provider": "chromadb", # or "qdrant" + "config": { + # "settings": Settings(persist_directory="/content/chroma", allow_reset=True, is_persistent=True), + # from qdrant_client.models import VectorParams, Distance + # "vectors_config": VectorParams(size=384, distance=Distance.COSINE), + } + }, + } +) +``` diff --git a/docs/ar/tools/file-document/ocrtool.mdx b/docs/ar/tools/file-document/ocrtool.mdx new file mode 100644 index 000000000..b4d12faed --- /dev/null +++ b/docs/ar/tools/file-document/ocrtool.mdx @@ -0,0 +1,88 @@ +--- +title: أداة OCR +description: تستخرج `OCRTool` النص من الصور المحلية أو عناوين URL للصور باستخدام نموذج LLM مزود بالرؤية. +icon: image +mode: "wide" +--- + +# `OCRTool` + +## الوصف + +استخراج النص من الصور (مسار محلي أو عنوان URL). تستخدم نموذج LLM مزوداً بالرؤية عبر واجهة LLM الخاصة بـ CrewAI. + +## التثبيت + +لا حاجة لتثبيت إضافي بخلاف `crewai-tools`. تأكد من أن النموذج المحدد يدعم الرؤية. + +## المعاملات + +### معاملات التشغيل + +- `image_path_url` (str, مطلوب): مسار صورة محلية أو عنوان URL بروتوكول HTTP(S). + +## أمثلة + +### الاستخدام المباشر + +```python Code +from crewai_tools import OCRTool + +print(OCRTool().run(image_path_url="/tmp/receipt.png")) +``` + +### مع وكيل + +```python Code +from crewai import Agent, Task, Crew +from crewai_tools import OCRTool + +ocr = OCRTool() + +agent = Agent( + role="OCR", + goal="Extract text", + tools=[ocr], +) + +task = Task( + description="Extract text from https://example.com/invoice.jpg", + expected_output="All detected text in plain text", + agent=agent, +) + +crew = Crew(agents=[agent], tasks=[task]) +result = crew.kickoff() +``` + +## ملاحظات + +- تأكد من أن النموذج المحدد يدعم مدخلات الصور. +- للصور الكبيرة، فكر في تصغير الحجم لتقليل استهلاك الرموز. + - يمكنك تمرير نسخة LLM محددة للأداة (مثل `LLM(model="gpt-4o")`) إذا لزم الأمر، وفقاً لتوجيهات README. + +## مثال + +```python Code +from crewai import Agent, Task, Crew +from crewai_tools import OCRTool + +tool = OCRTool() + +agent = Agent( + role="OCR Specialist", + goal="Extract text from images", + backstory="Vision‑enabled analyst", + tools=[tool], + verbose=True, +) + +task = Task( + description="Extract text from https://example.com/receipt.png", + expected_output="All detected text in plain text", + agent=agent, +) + +crew = Crew(agents=[agent], tasks=[task]) +result = crew.kickoff() +``` diff --git a/docs/ar/tools/file-document/overview.mdx b/docs/ar/tools/file-document/overview.mdx new file mode 100644 index 000000000..c547c763d --- /dev/null +++ b/docs/ar/tools/file-document/overview.mdx @@ -0,0 +1,97 @@ +--- +title: "نظرة عامة" +description: "قراءة وكتابة والبحث في صيغ ملفات متنوعة باستخدام أدوات معالجة المستندات من CrewAI" +icon: "face-smile" +mode: "wide" +--- + +تتيح هذه الأدوات لوكلائك العمل مع صيغ ملفات وأنواع مستندات متنوعة. من قراءة ملفات PDF إلى معالجة بيانات JSON، تتعامل هذه الأدوات مع جميع احتياجات معالجة المستندات الخاصة بك. + +## **الأدوات المتاحة** + + + + قراءة المحتوى من أي نوع ملف بما في ذلك النصوص و Markdown والمزيد. + + + + كتابة المحتوى في الملفات وإنشاء مستندات جديدة وحفظ البيانات المعالجة. + + + + البحث واستخراج محتوى نصي من مستندات PDF بكفاءة. + + + + البحث في مستندات Microsoft Word واستخراج المحتوى ذي الصلة. + + + + تحليل والبحث في ملفات JSON بإمكانيات استعلام متقدمة. + + + + معالجة والبحث في ملفات CSV واستخراج صفوف وأعمدة محددة. + + + + تحليل ملفات XML والبحث عن عناصر وخصائص محددة. + + + + البحث في ملفات MDX واستخراج المحتوى من الوثائق. + + + + البحث في ملفات النص العادي بإمكانيات مطابقة الأنماط. + + + + البحث عن الملفات والمجلدات داخل هياكل المجلدات. + + + + قراءة وعرض محتويات المجلدات وهياكل الملفات والبيانات الوصفية. + + + + استخراج النص من الصور (ملفات محلية أو عناوين URL) باستخدام نموذج LLM مزود بالرؤية. + + + + كتابة نص في إحداثيات محددة في ملفات PDF، مع خطوط مخصصة اختيارية. + + + +## **حالات الاستخدام الشائعة** + +- **معالجة المستندات**: استخراج وتحليل المحتوى من صيغ ملفات متنوعة +- **استيراد البيانات**: قراءة بيانات منظمة من ملفات CSV و JSON و XML +- **بحث المحتوى**: العثور على معلومات محددة داخل مجموعات مستندات كبيرة +- **إدارة الملفات**: تنظيم ومعالجة الملفات والمجلدات +- **تصدير البيانات**: حفظ النتائج المعالجة في صيغ ملفات متنوعة + +## **مثال للبدء السريع** + +```python +from crewai_tools import FileReadTool, PDFSearchTool, JSONSearchTool + +# Create tools +file_reader = FileReadTool() +pdf_searcher = PDFSearchTool() +json_processor = JSONSearchTool() + +# Add to your agent +agent = Agent( + role="Document Analyst", + tools=[file_reader, pdf_searcher, json_processor], + goal="Process and analyze various document types" +) +``` + +## **نصائح لمعالجة المستندات** + +- **صلاحيات الملفات**: تأكد من أن وكيلك لديه صلاحيات القراءة/الكتابة المناسبة +- **الملفات الكبيرة**: فكر في التقسيم إلى أجزاء للمستندات الكبيرة جداً +- **دعم الصيغ**: راجع وثائق الأداة لمعرفة صيغ الملفات المدعومة +- **معالجة الأخطاء**: طبّق معالجة أخطاء مناسبة للملفات التالفة أو التي يتعذر الوصول إليها diff --git a/docs/ar/tools/file-document/pdf-text-writing-tool.mdx b/docs/ar/tools/file-document/pdf-text-writing-tool.mdx new file mode 100644 index 000000000..86bca0227 --- /dev/null +++ b/docs/ar/tools/file-document/pdf-text-writing-tool.mdx @@ -0,0 +1,75 @@ +--- +title: أداة كتابة نص PDF +description: تكتب `PDFTextWritingTool` نصاً في مواضع محددة في ملف PDF، مع دعم الخطوط المخصصة. +icon: file-pdf +mode: "wide" +--- + +# `PDFTextWritingTool` + +## الوصف + +كتابة نص في إحداثيات دقيقة على صفحة PDF، مع إمكانية تضمين خط TrueType مخصص اختيارياً. + +## المعاملات + +### معاملات التشغيل + +- `pdf_path` (str, مطلوب): مسار ملف PDF المدخل. +- `text` (str, مطلوب): النص المراد إضافته. +- `position` (tuple[int, int], مطلوب): إحداثيات `(x, y)`. +- `font_size` (int, الافتراضي `12`) +- `font_color` (str, الافتراضي `"0 0 0 rg"`) +- `font_name` (str, الافتراضي `"F1"`) +- `font_file` (str, اختياري): مسار ملف `.ttf`. +- `page_number` (int, الافتراضي `0`) + +## مثال + +```python Code +from crewai import Agent, Task, Crew +from crewai_tools import PDFTextWritingTool + +tool = PDFTextWritingTool() + +agent = Agent( + role="PDF Editor", + goal="Annotate PDFs", + backstory="Documentation specialist", + tools=[tool], + verbose=True, +) + +task = Task( + description="Write 'CONFIDENTIAL' at (72, 720) on page 1 of ./sample.pdf", + expected_output="Confirmation message", + agent=agent, +) + +crew = Crew( + agents=[agent], + tasks=[task], + verbose=True, +) + +result = crew.kickoff() +``` + +### الاستخدام المباشر + +```python Code +from crewai_tools import PDFTextWritingTool + +PDFTextWritingTool().run( + pdf_path="./input.pdf", + text="CONFIDENTIAL", + position=(72, 720), + font_size=18, + page_number=0, +) +``` + +## نصائح + +- نقطة أصل الإحداثيات هي الزاوية السفلية اليسرى. +- إذا كنت تستخدم خطاً مخصصاً (`font_file`)، تأكد من أنه ملف `.ttf` صالح. diff --git a/docs/ar/tools/file-document/pdfsearchtool.mdx b/docs/ar/tools/file-document/pdfsearchtool.mdx new file mode 100644 index 000000000..86e0272ad --- /dev/null +++ b/docs/ar/tools/file-document/pdfsearchtool.mdx @@ -0,0 +1,107 @@ +--- +title: بحث RAG في PDF +description: أداة `PDFSearchTool` مصممة للبحث في ملفات PDF وإرجاع النتائج الأكثر صلة. +icon: file-pdf +mode: "wide" +--- + +# `PDFSearchTool` + + + لا نزال نعمل على تحسين الأدوات، لذا قد يحدث سلوك غير متوقع أو تغييرات في المستقبل. + + +## الوصف + +أداة PDFSearchTool هي أداة RAG مصممة لعمليات البحث الدلالي داخل محتوى PDF. تتيح إدخال استعلام بحث ومستند PDF، مستفيدة من تقنيات بحث متقدمة للعثور على المحتوى ذي الصلة بكفاءة. هذه القدرة تجعلها مفيدة بشكل خاص لاستخراج معلومات محددة من ملفات PDF الكبيرة بسرعة. + +## التثبيت + +للبدء مع أداة PDFSearchTool، تأكد أولاً من تثبيت حزمة crewai_tools بالأمر التالي: + +```shell +pip install 'crewai[tools]' +``` + +## مثال +إليك كيفية استخدام PDFSearchTool للبحث داخل مستند PDF: + +```python Code +from crewai_tools import PDFSearchTool + +# Initialize the tool allowing for any PDF content search if the path is provided during execution +tool = PDFSearchTool() + +# OR + +# Initialize the tool with a specific PDF path for exclusive search within that document +tool = PDFSearchTool(pdf='path/to/your/document.pdf') +``` + +## المعاملات + +- `pdf`: **اختياري** مسار ملف PDF للبحث. يمكن تقديمه عند التهيئة أو ضمن معاملات طريقة `run`. إذا قُدم عند التهيئة، تقتصر الأداة في بحثها على المستند المحدد. + +## النموذج والتضمينات المخصصة + +بشكل افتراضي، تستخدم الأداة OpenAI لكل من التضمينات والتلخيص. لتخصيص النموذج، يمكنك استخدام قاموس تكوين كما يلي. ملاحظة: قاعدة بيانات متجهية مطلوبة لأن التضمينات المولّدة يجب تخزينها والاستعلام عنها من قاعدة بيانات متجهية. + +```python Code +from crewai_tools import PDFSearchTool + +# - embedding_model (required): choose provider + provider-specific config +# - vectordb (required): choose vector DB and pass its config + +tool = PDFSearchTool( + config={ + "embedding_model": { + # Supported providers: "openai", "azure", "google-generativeai", "google-vertex", + # "voyageai", "cohere", "huggingface", "jina", "sentence-transformer", + # "text2vec", "ollama", "openclip", "instructor", "onnx", "roboflow", "watsonx", "custom" + "provider": "openai", # or: "google-generativeai", "cohere", "ollama", ... + "config": { + # Model identifier for the chosen provider. "model" will be auto-mapped to "model_name" internally. + "model": "text-embedding-3-small", + # Optional: API key. If omitted, the tool will use provider-specific env vars + # (e.g., OPENAI_API_KEY or EMBEDDINGS_OPENAI_API_KEY for OpenAI). + # "api_key": "sk-...", + + # Provider-specific examples: + # --- Google Generative AI --- + # (Set provider="google-generativeai" above) + # "model_name": "gemini-embedding-001", + # "task_type": "RETRIEVAL_DOCUMENT", + # "title": "Embeddings", + + # --- Cohere --- + # (Set provider="cohere" above) + # "model": "embed-english-v3.0", + + # --- Ollama (local) --- + # (Set provider="ollama" above) + # "model": "nomic-embed-text", + }, + }, + "vectordb": { + "provider": "chromadb", # or "qdrant" + "config": { + # For ChromaDB: pass "settings" (chromadb.config.Settings) or rely on defaults. + # Example (uncomment and import): + # from chromadb.config import Settings + # "settings": Settings( + # persist_directory="/content/chroma", + # allow_reset=True, + # is_persistent=True, + # ), + + # For Qdrant: pass "vectors_config" (qdrant_client.models.VectorParams). + # Example (uncomment and import): + # from qdrant_client.models import VectorParams, Distance + # "vectors_config": VectorParams(size=384, distance=Distance.COSINE), + + # Note: collection name is controlled by the tool (default: "rag_tool_collection"), not set here. + } + }, + } +) +``` diff --git a/docs/ar/tools/file-document/txtsearchtool.mdx b/docs/ar/tools/file-document/txtsearchtool.mdx new file mode 100644 index 000000000..9f253141f --- /dev/null +++ b/docs/ar/tools/file-document/txtsearchtool.mdx @@ -0,0 +1,89 @@ +--- +title: بحث RAG في TXT +description: أداة `TXTSearchTool` مصممة لإجراء بحث RAG (الاسترجاع المعزز بالتوليد) داخل محتوى ملف نصي. +icon: file-lines +mode: "wide" +--- + +## نظرة عامة + + + لا نزال نعمل على تحسين الأدوات، لذا قد يحدث سلوك غير متوقع أو تغييرات في المستقبل. + + +تُستخدم هذه الأداة لإجراء بحث RAG (الاسترجاع المعزز بالتوليد) داخل محتوى ملف نصي. تتيح البحث الدلالي عن استعلام داخل محتوى ملف نصي محدد، مما يجعلها مورداً لا يُقدَّر بثمن لاستخراج المعلومات بسرعة أو العثور على أقسام محددة من النص بناءً على الاستعلام المقدم. + +## التثبيت + +لاستخدام `TXTSearchTool`، تحتاج أولاً إلى تثبيت حزمة `crewai_tools`. يمكن القيام بذلك باستخدام pip، مدير الحزم لـ Python. افتح الطرفية أو موجه الأوامر وأدخل الأمر التالي: + +```shell +pip install 'crewai[tools]' +``` + +سيقوم هذا الأمر بتنزيل وتثبيت TXTSearchTool مع أي تبعيات ضرورية. + +## مثال + +يوضح المثال التالي كيفية استخدام TXTSearchTool للبحث داخل ملف نصي. يعرض هذا المثال كلاً من تهيئة الأداة بملف نصي محدد والبحث اللاحق داخل محتوى ذلك الملف. + +```python Code +from crewai_tools import TXTSearchTool + +# Initialize the tool to search within any text file's content +# the agent learns about during its execution +tool = TXTSearchTool() + +# OR + +# Initialize the tool with a specific text file, +# so the agent can search within the given text file's content +tool = TXTSearchTool(txt='path/to/text/file.txt') +``` + +## المعاملات +- `txt` (str): **اختياري**. مسار الملف النصي المراد البحث فيه. هذا المعامل مطلوب فقط إذا لم يتم تهيئة الأداة بملف نصي محدد؛ وإلا سيتم إجراء البحث داخل الملف النصي المقدم مبدئياً. + +## النموذج والتضمينات المخصصة + +بشكل افتراضي، تستخدم الأداة OpenAI لكل من التضمينات والتلخيص. لتخصيص النموذج، يمكنك استخدام قاموس تكوين كما يلي: + +```python Code +from chromadb.config import Settings + +tool = TXTSearchTool( + config={ + # Required: embeddings provider + config + "embedding_model": { + "provider": "openai", # or google-generativeai, cohere, ollama, ... + "config": { + "model": "text-embedding-3-small", + # "api_key": "sk-...", # optional if env var is set (e.g., OPENAI_API_KEY or EMBEDDINGS_OPENAI_API_KEY) + # Provider examples: + # Google → model_name: "gemini-embedding-001", task_type: "RETRIEVAL_DOCUMENT" + # Cohere → model: "embed-english-v3.0" + # Ollama → model: "nomic-embed-text" + }, + }, + + # Required: vector database config + "vectordb": { + "provider": "chromadb", # or "qdrant" + "config": { + # Chroma settings (optional persistence) + # "settings": Settings( + # persist_directory="/content/chroma", + # allow_reset=True, + # is_persistent=True, + # ), + + # Qdrant vector params example: + # from qdrant_client.models import VectorParams, Distance + # "vectors_config": VectorParams(size=384, distance=Distance.COSINE), + + # Note: collection name is controlled by the tool (default: "rag_tool_collection"). + } + }, + } +) +``` diff --git a/docs/ar/tools/file-document/xmlsearchtool.mdx b/docs/ar/tools/file-document/xmlsearchtool.mdx new file mode 100644 index 000000000..d82c57b0e --- /dev/null +++ b/docs/ar/tools/file-document/xmlsearchtool.mdx @@ -0,0 +1,74 @@ +--- +title: بحث RAG في XML +description: أداة `XMLSearchTool` مصممة لإجراء بحث RAG (الاسترجاع المعزز بالتوليد) داخل محتوى ملف XML. +icon: file-xml +mode: "wide" +--- + +# `XMLSearchTool` + + + لا نزال نعمل على تحسين الأدوات، لذا قد يحدث سلوك غير متوقع أو تغييرات في المستقبل. + + +## الوصف + +أداة XMLSearchTool هي أداة RAG متطورة مصممة لإجراء عمليات بحث دلالي داخل ملفات XML. مثالية للمستخدمين الذين يحتاجون إلى تحليل واستخراج المعلومات من محتوى XML بكفاءة، تدعم هذه الأداة إدخال استعلام بحث ومسار ملف XML اختياري. من خلال تحديد مسار XML، يمكن للمستخدمين استهداف بحثهم بدقة أكبر نحو محتوى ذلك الملف، وبالتالي الحصول على نتائج بحث أكثر صلة. + +## التثبيت + +للبدء باستخدام XMLSearchTool، يجب أولاً تثبيت حزمة crewai_tools. يمكن القيام بذلك بسهولة بالأمر التالي: + +```shell +pip install 'crewai[tools]' +``` + +## مثال + +فيما يلي مثالان يوضحان كيفية استخدام XMLSearchTool. المثال الأول يوضح البحث داخل ملف XML محدد، بينما يوضح المثال الثاني بدء بحث بدون تحديد مسار XML مسبقاً، مما يوفر مرونة في نطاق البحث. + +```python Code +from crewai_tools import XMLSearchTool + +# Allow agents to search within any XML file's content +#as it learns about their paths during execution +tool = XMLSearchTool() + +# OR + +# Initialize the tool with a specific XML file path +#for exclusive search within that document +tool = XMLSearchTool(xml='path/to/your/xmlfile.xml') +``` + +## المعاملات + +- `xml`: مسار ملف XML المراد البحث فيه. هذا معامل اختياري أثناء تهيئة الأداة ولكن يجب تقديمه إما عند التهيئة أو كجزء من معاملات طريقة `run` لتنفيذ البحث. + +## النموذج والتضمينات المخصصة + +بشكل افتراضي، تستخدم الأداة OpenAI لكل من التضمينات والتلخيص. لتخصيص النموذج، يمكنك استخدام قاموس تكوين كما يلي: + +```python Code +from chromadb.config import Settings + +tool = XMLSearchTool( + config={ + "embedding_model": { + "provider": "openai", + "config": { + "model": "text-embedding-3-small", + # "api_key": "sk-...", + }, + }, + "vectordb": { + "provider": "chromadb", # or "qdrant" + "config": { + # "settings": Settings(persist_directory="/content/chroma", allow_reset=True, is_persistent=True), + # from qdrant_client.models import VectorParams, Distance + # "vectors_config": VectorParams(size=384, distance=Distance.COSINE), + } + }, + } +) +``` diff --git a/docs/ar/tools/integration/bedrockinvokeagenttool.mdx b/docs/ar/tools/integration/bedrockinvokeagenttool.mdx new file mode 100644 index 000000000..24b650889 --- /dev/null +++ b/docs/ar/tools/integration/bedrockinvokeagenttool.mdx @@ -0,0 +1,188 @@ +--- +title: أداة استدعاء وكيل Bedrock +description: تتيح لوكلاء CrewAI استدعاء وكلاء Amazon Bedrock والاستفادة من قدراتهم ضمن سير العمل الخاص بك +icon: aws +mode: "wide" +--- + +# `BedrockInvokeAgentTool` + +تتيح `BedrockInvokeAgentTool` لوكلاء CrewAI استدعاء وكلاء Amazon Bedrock والاستفادة من قدراتهم ضمن سير العمل الخاص بك. + +## التثبيت + +```bash +uv pip install 'crewai[tools]' +``` + +## المتطلبات + +- بيانات اعتماد AWS مُهيأة (إما من خلال متغيرات البيئة أو AWS CLI) +- حزمتا `boto3` و `python-dotenv` +- الوصول إلى وكلاء Amazon Bedrock + +## الاستخدام + +إليك كيفية استخدام الأداة مع وكيل CrewAI: + +```python {2, 4-8} +from crewai import Agent, Task, Crew +from crewai_tools.aws.bedrock.agents.invoke_agent_tool import BedrockInvokeAgentTool + +# Initialize the tool +agent_tool = BedrockInvokeAgentTool( + agent_id="your-agent-id", + agent_alias_id="your-agent-alias-id" +) + +# Create a CrewAI agent that uses the tool +aws_expert = Agent( + role='AWS Service Expert', + goal='Help users understand AWS services and quotas', + backstory='I am an expert in AWS services and can provide detailed information about them.', + tools=[agent_tool], + verbose=True +) + +# Create a task for the agent +quota_task = Task( + description="Find out the current service quotas for EC2 in us-west-2 and explain any recent changes.", + agent=aws_expert +) + +# Create a crew with the agent +crew = Crew( + agents=[aws_expert], + tasks=[quota_task], + verbose=2 +) + +# Run the crew +result = crew.kickoff() +print(result) +``` + +## معاملات الأداة + +| المعامل | النوع | مطلوب | الافتراضي | الوصف | +|:---------|:-----|:---------|:--------|:------------| +| **agent_id** | `str` | نعم | None | المعرّف الفريد لوكيل Bedrock | +| **agent_alias_id** | `str` | نعم | None | المعرّف الفريد لاسم الوكيل المستعار | +| **session_id** | `str` | لا | الطابع الزمني | المعرّف الفريد للجلسة | +| **enable_trace** | `bool` | لا | False | ما إذا كان سيتم تفعيل التتبع لأغراض التصحيح | +| **end_session** | `bool` | لا | False | ما إذا كان سيتم إنهاء الجلسة بعد الاستدعاء | +| **description** | `str` | لا | None | وصف مخصص للأداة | + +## متغيرات البيئة + +```bash +BEDROCK_AGENT_ID=your-agent-id # Alternative to passing agent_id +BEDROCK_AGENT_ALIAS_ID=your-agent-alias-id # Alternative to passing agent_alias_id +AWS_REGION=your-aws-region # Defaults to us-west-2 +AWS_ACCESS_KEY_ID=your-access-key # Required for AWS authentication +AWS_SECRET_ACCESS_KEY=your-secret-key # Required for AWS authentication +``` + +## الاستخدام المتقدم + +### سير عمل متعدد الوكلاء مع إدارة الجلسات + +```python {2, 4-22} +from crewai import Agent, Task, Crew, Process +from crewai_tools.aws.bedrock.agents.invoke_agent_tool import BedrockInvokeAgentTool + +# Initialize tools with session management +initial_tool = BedrockInvokeAgentTool( + agent_id="your-agent-id", + agent_alias_id="your-agent-alias-id", + session_id="custom-session-id" +) + +followup_tool = BedrockInvokeAgentTool( + agent_id="your-agent-id", + agent_alias_id="your-agent-alias-id", + session_id="custom-session-id" +) + +final_tool = BedrockInvokeAgentTool( + agent_id="your-agent-id", + agent_alias_id="your-agent-alias-id", + session_id="custom-session-id", + end_session=True +) + +# Create agents for different stages +researcher = Agent( + role='AWS Service Researcher', + goal='Gather information about AWS services', + backstory='I am specialized in finding detailed AWS service information.', + tools=[initial_tool] +) + +analyst = Agent( + role='Service Compatibility Analyst', + goal='Analyze service compatibility and requirements', + backstory='I analyze AWS services for compatibility and integration possibilities.', + tools=[followup_tool] +) + +summarizer = Agent( + role='Technical Documentation Writer', + goal='Create clear technical summaries', + backstory='I specialize in creating clear, concise technical documentation.', + tools=[final_tool] +) + +# Create tasks +research_task = Task( + description="Find all available AWS services in us-west-2 region.", + agent=researcher +) + +analysis_task = Task( + description="Analyze which services support IPv6 and their implementation requirements.", + agent=analyst +) + +summary_task = Task( + description="Create a summary of IPv6-compatible services and their key features.", + agent=summarizer +) + +# Create a crew with the agents and tasks +crew = Crew( + agents=[researcher, analyst, summarizer], + tasks=[research_task, analysis_task, summary_task], + process=Process.sequential, + verbose=2 +) + +# Run the crew +result = crew.kickoff() +``` + +## حالات الاستخدام + +### التعاون الهجين متعدد الوكلاء +- إنشاء سير عمل حيث يتعاون وكلاء CrewAI مع وكلاء Bedrock المُدارة التي تعمل كخدمات في AWS +- تمكين سيناريوهات حيث تتم معالجة البيانات الحساسة داخل بيئة AWS الخاصة بك بينما تعمل وكلاء أخرى خارجياً +- ربط وكلاء CrewAI المحلية مع وكلاء Bedrock السحابية لسير عمل ذكاء موزع + +### سيادة البيانات والامتثال +- الحفاظ على سير عمل الوكلاء الحساسة للبيانات داخل بيئة AWS الخاصة بك مع السماح لوكلاء CrewAI الخارجية بتنسيق المهام +- الحفاظ على الامتثال لمتطلبات إقامة البيانات من خلال معالجة المعلومات الحساسة فقط داخل حساب AWS الخاص بك +- تمكين التعاون الآمن متعدد الوكلاء حيث لا يمكن لبعض الوكلاء الوصول إلى البيانات الخاصة بمؤسستك + +### التكامل السلس مع خدمات AWS +- الوصول إلى أي خدمة AWS من خلال Amazon Bedrock Actions دون كتابة كود تكامل معقد +- تمكين وكلاء CrewAI من التفاعل مع خدمات AWS من خلال طلبات اللغة الطبيعية +- الاستفادة من قدرات وكلاء Bedrock المبنية مسبقاً للتفاعل مع خدمات AWS مثل Bedrock Knowledge Bases و Lambda والمزيد + +### هياكل وكلاء هجينة قابلة للتوسع +- تفريغ المهام الحسابية المكثفة إلى وكلاء Bedrock المُدارة بينما تعمل المهام الخفيفة في CrewAI +- توسيع معالجة الوكلاء من خلال توزيع أعباء العمل بين وكلاء CrewAI المحلية ووكلاء Bedrock السحابية + +### التعاون بين المؤسسات +- تمكين التعاون الآمن بين وكلاء CrewAI الخاصة بمؤسستك ووكلاء Bedrock الخاصة بالمؤسسات الشريكة +- إنشاء سير عمل حيث يمكن دمج الخبرة الخارجية من وكلاء Bedrock دون كشف البيانات الحساسة +- بناء أنظمة وكلاء تمتد عبر حدود المؤسسات مع الحفاظ على الأمان والتحكم في البيانات diff --git a/docs/ar/tools/integration/crewaiautomationtool.mdx b/docs/ar/tools/integration/crewaiautomationtool.mdx new file mode 100644 index 000000000..6ee8778f4 --- /dev/null +++ b/docs/ar/tools/integration/crewaiautomationtool.mdx @@ -0,0 +1,276 @@ +--- +title: أداة تشغيل أتمتة CrewAI +description: تتيح لوكلاء CrewAI استدعاء أتمتة منصة CrewAI والاستفادة من خدمات الأطقم الخارجية ضمن سير العمل الخاص بك. +icon: robot +--- + +# `InvokeCrewAIAutomationTool` + +توفر `InvokeCrewAIAutomationTool` تكاملاً مع واجهة برمجة تطبيقات منصة CrewAI مع خدمات الأطقم الخارجية. تتيح لك هذه الأداة استدعاء أتمتة منصة CrewAI والتفاعل معها من داخل وكلاء CrewAI، مما يمكّن التكامل السلس بين سير عمل الأطقم المختلفة. + +## التثبيت + +```bash +uv pip install 'crewai[tools]' +``` + +## المتطلبات + +- الوصول إلى واجهة برمجة تطبيقات منصة CrewAI +- رمز حامل صالح للمصادقة +- الوصول الشبكي إلى نقاط نهاية أتمتة منصة CrewAI + +## الاستخدام + +إليك كيفية استخدام الأداة مع وكيل CrewAI: + +```python {2, 4-9} +from crewai import Agent, Task, Crew +from crewai_tools import InvokeCrewAIAutomationTool + +# Initialize the tool +automation_tool = InvokeCrewAIAutomationTool( + crew_api_url="https://data-analysis-crew-[...].crewai.com", + crew_bearer_token="your_bearer_token_here", + crew_name="Data Analysis Crew", + crew_description="Analyzes data and generates insights" +) + +# Create a CrewAI agent that uses the tool +automation_coordinator = Agent( + role='Automation Coordinator', + goal='Coordinate and execute automated crew tasks', + backstory='I am an expert at leveraging automation tools to execute complex workflows.', + tools=[automation_tool], + verbose=True +) + +# Create a task for the agent +analysis_task = Task( + description="Execute data analysis automation and provide insights", + agent=automation_coordinator, + expected_output="Comprehensive data analysis report" +) + +# Create a crew with the agent +crew = Crew( + agents=[automation_coordinator], + tasks=[analysis_task], + verbose=2 +) + +# Run the crew +result = crew.kickoff() +print(result) +``` + +## معاملات الأداة + +| المعامل | النوع | مطلوب | الافتراضي | الوصف | +|:---------|:-----|:---------|:--------|:------------| +| **crew_api_url** | `str` | نعم | None | عنوان URL الأساسي لواجهة برمجة تطبيقات أتمتة منصة CrewAI | +| **crew_bearer_token** | `str` | نعم | None | رمز حامل لمصادقة API | +| **crew_name** | `str` | نعم | None | اسم أتمتة الطاقم | +| **crew_description** | `str` | نعم | None | وصف ما تفعله أتمتة الطاقم | +| **max_polling_time** | `int` | لا | 600 | الحد الأقصى للوقت بالثواني للانتظار حتى اكتمال المهمة | +| **crew_inputs** | `dict` | لا | None | قاموس يحدد حقول مخطط المدخلات المخصصة | + +## متغيرات البيئة + +```bash +CREWAI_API_URL=https://your-crew-automation.crewai.com # Alternative to passing crew_api_url +CREWAI_BEARER_TOKEN=your_bearer_token_here # Alternative to passing crew_bearer_token +``` + +## الاستخدام المتقدم + +### مخطط مدخلات مخصص مع معاملات ديناميكية + +```python {2, 4-15} +from crewai import Agent, Task, Crew +from crewai_tools import InvokeCrewAIAutomationTool +from pydantic import Field + +# Define custom input schema +custom_inputs = { + "year": Field(..., description="Year to retrieve the report for (integer)"), + "region": Field(default="global", description="Geographic region for analysis"), + "format": Field(default="summary", description="Report format (summary, detailed, raw)") +} + +# Create tool with custom inputs +market_research_tool = InvokeCrewAIAutomationTool( + crew_api_url="https://state-of-ai-report-crew-[...].crewai.com", + crew_bearer_token="your_bearer_token_here", + crew_name="State of AI Report", + crew_description="Retrieves a comprehensive report on state of AI for a given year and region", + crew_inputs=custom_inputs, + max_polling_time=15 * 60 # 15 minutes timeout +) + +# Create an agent with the tool +research_agent = Agent( + role="Research Coordinator", + goal="Coordinate and execute market research tasks", + backstory="You are an expert at coordinating research tasks and leveraging automation tools.", + tools=[market_research_tool], + verbose=True +) + +# Create and execute a task with custom parameters +research_task = Task( + description="Conduct market research on AI tools market for 2024 in North America with detailed format", + agent=research_agent, + expected_output="Comprehensive market research report" +) + +crew = Crew( + agents=[research_agent], + tasks=[research_task] +) + +result = crew.kickoff() +``` + +### سير عمل أتمتة متعدد المراحل + +```python {2, 4-35} +from crewai import Agent, Task, Crew, Process +from crewai_tools import InvokeCrewAIAutomationTool + +# Initialize different automation tools +data_collection_tool = InvokeCrewAIAutomationTool( + crew_api_url="https://data-collection-crew-[...].crewai.com", + crew_bearer_token="your_bearer_token_here", + crew_name="Data Collection Automation", + crew_description="Collects and preprocesses raw data" +) + +analysis_tool = InvokeCrewAIAutomationTool( + crew_api_url="https://analysis-crew-[...].crewai.com", + crew_bearer_token="your_bearer_token_here", + crew_name="Analysis Automation", + crew_description="Performs advanced data analysis and modeling" +) + +reporting_tool = InvokeCrewAIAutomationTool( + crew_api_url="https://reporting-crew-[...].crewai.com", + crew_bearer_token="your_bearer_token_here", + crew_name="Reporting Automation", + crew_description="Generates comprehensive reports and visualizations" +) + +# Create specialized agents +data_collector = Agent( + role='Data Collection Specialist', + goal='Gather and preprocess data from various sources', + backstory='I specialize in collecting and cleaning data from multiple sources.', + tools=[data_collection_tool] +) + +data_analyst = Agent( + role='Data Analysis Expert', + goal='Perform advanced analysis on collected data', + backstory='I am an expert in statistical analysis and machine learning.', + tools=[analysis_tool] +) + +report_generator = Agent( + role='Report Generation Specialist', + goal='Create comprehensive reports and visualizations', + backstory='I excel at creating clear, actionable reports from complex data.', + tools=[reporting_tool] +) + +# Create sequential tasks +collection_task = Task( + description="Collect market data for Q4 2024 analysis", + agent=data_collector +) + +analysis_task = Task( + description="Analyze collected data to identify trends and patterns", + agent=data_analyst +) + +reporting_task = Task( + description="Generate executive summary report with key insights and recommendations", + agent=report_generator +) + +# Create a crew with sequential processing +crew = Crew( + agents=[data_collector, data_analyst, report_generator], + tasks=[collection_task, analysis_task, reporting_task], + process=Process.sequential, + verbose=2 +) + +result = crew.kickoff() +``` + +## حالات الاستخدام + +### تنسيق الأطقم الموزعة +- تنسيق أتمتة أطقم متخصصة متعددة للتعامل مع سير عمل معقدة ومتعددة المراحل +- تمكين عمليات التسليم السلسة بين خدمات الأتمتة المختلفة لتنفيذ شامل للمهام +- توسيع المعالجة من خلال توزيع أعباء العمل عبر أتمتة منصة CrewAI المتعددة + +### التكامل عبر المنصات +- ربط وكلاء CrewAI مع أتمتة منصة CrewAI لسير عمل محلي-سحابي هجين +- الاستفادة من الأتمتة المتخصصة مع الحفاظ على التحكم والتنسيق المحلي +- تمكين التعاون الآمن بين الوكلاء المحليين وخدمات الأتمتة السحابية + +### خطوط أنابيب أتمتة المؤسسات +- إنشاء خطوط أنابيب أتمتة بمستوى المؤسسة تجمع بين الذكاء المحلي وقوة المعالجة السحابية +- تنفيذ سير عمل أعمال معقدة تمتد عبر خدمات أتمتة متعددة +- تمكين عمليات قابلة للتوسع ومتكررة لتحليل البيانات وإعداد التقارير واتخاذ القرارات + +### تركيب سير العمل الديناميكي +- تركيب سير العمل ديناميكياً من خلال تسلسل خدمات أتمتة مختلفة بناءً على متطلبات المهمة +- تمكين المعالجة التكيفية حيث يعتمد اختيار الأتمتة على خصائص البيانات أو قواعد العمل +- إنشاء مكونات أتمتة مرنة وقابلة لإعادة الاستخدام يمكن دمجها بطرق مختلفة + +### المعالجة المتخصصة بالمجال +- الوصول إلى أتمتة خاصة بالمجال (التحليل المالي، البحث القانوني، التوثيق التقني) من وكلاء ذات أغراض عامة +- الاستفادة من أتمتة أطقم متخصصة مبنية مسبقاً دون إعادة بناء منطق المجال المعقد +- تمكين الوكلاء من الوصول إلى قدرات مستوى الخبراء من خلال خدمات أتمتة مستهدفة + +## مخطط المدخلات المخصص + +عند تعريف `crew_inputs`، استخدم كائنات Pydantic Field لتحديد معاملات المدخلات: + +```python +from pydantic import Field + +crew_inputs = { + "required_param": Field(..., description="This parameter is required"), + "optional_param": Field(default="default_value", description="This parameter is optional"), + "typed_param": Field(..., description="Integer parameter", ge=1, le=100) # With validation +} +``` + +## معالجة الأخطاء + +توفر الأداة معالجة شاملة للأخطاء للسيناريوهات الشائعة: + +- **أخطاء اتصال API**: مشكلات الاتصال الشبكي مع منصة CrewAI +- **أخطاء المصادقة**: رموز حامل غير صالحة أو منتهية الصلاحية +- **أخطاء المهلة**: المهام التي تتجاوز الحد الأقصى لوقت الاستقصاء +- **فشل المهام**: أتمتة الأطقم التي تفشل أثناء التنفيذ +- **أخطاء التحقق من المدخلات**: معاملات غير صالحة مُمررة إلى نقاط نهاية الأتمتة + +## نقاط نهاية API + +تتفاعل الأداة مع نقطتي نهاية API رئيسيتين: + +- `POST {crew_api_url}/kickoff`: بدء مهمة أتمتة طاقم جديدة +- `GET {crew_api_url}/status/{crew_id}`: التحقق من حالة مهمة قيد التشغيل + +## ملاحظات + +- تقوم الأداة تلقائياً باستقصاء نقطة نهاية الحالة كل ثانية حتى الاكتمال أو انتهاء المهلة +- تُرجع المهام الناجحة النتيجة مباشرة، بينما تُرجع المهام الفاشلة معلومات الخطأ +- يجب الحفاظ على أمان رموز الحامل وعدم ترميزها بشكل ثابت في بيئات الإنتاج +- فكر في استخدام متغيرات البيئة للتكوينات الحساسة مثل رموز الحامل +- يجب أن تكون مخططات المدخلات المخصصة متوافقة مع المعاملات المتوقعة لأتمتة الطاقم المستهدف diff --git a/docs/ar/tools/integration/mergeagenthandlertool.mdx b/docs/ar/tools/integration/mergeagenthandlertool.mdx new file mode 100644 index 000000000..8c492a953 --- /dev/null +++ b/docs/ar/tools/integration/mergeagenthandlertool.mdx @@ -0,0 +1,367 @@ +--- +title: أداة معالج وكيل Merge +description: تتيح لوكلاء CrewAI الوصول بأمان إلى تكاملات الأطراف الثالثة مثل Linear و GitHub و Slack والمزيد من خلال منصة معالج الوكيل من Merge +icon: diagram-project +mode: "wide" +--- + +# `MergeAgentHandlerTool` + +تتيح `MergeAgentHandlerTool` لوكلاء CrewAI الوصول بأمان إلى تكاملات الأطراف الثالثة من خلال منصة [معالج الوكيل من Merge](https://www.merge.dev/products/merge-agent-handler). يوفر معالج الوكيل موصلات جاهزة وآمنة لأدوات شائعة مثل Linear و GitHub و Slack و Notion ومئات غيرها - جميعها مع مصادقة وصلاحيات ومراقبة مدمجة. + +## التثبيت + +```bash +uv pip install 'crewai[tools]' +``` + +## المتطلبات + +- حساب معالج وكيل Merge مع حزمة أدوات مُهيأة +- مفتاح API لمعالج الوكيل +- مستخدم مسجل واحد على الأقل مرتبط بحزمة الأدوات الخاصة بك +- تكاملات أطراف ثالثة مُهيأة في حزمة الأدوات الخاصة بك + +## البدء مع معالج الوكيل + +1. **التسجيل** في حساب معالج وكيل Merge على [ah.merge.dev/signup](https://ah.merge.dev/signup) +2. **إنشاء حزمة أدوات** وتكوين التكاملات التي تحتاجها +3. **تسجيل المستخدمين** الذين سيقومون بالمصادقة مع خدمات الأطراف الثالثة +4. **الحصول على مفتاح API** من لوحة تحكم معالج الوكيل +5. **تعيين متغير البيئة**: `export AGENT_HANDLER_API_KEY='your-key-here'` +6. **البدء بالبناء** مع MergeAgentHandlerTool في CrewAI + +## ملاحظات + +- يمكن العثور على معرّفات حزمة الأدوات ومعرّفات المستخدمين المسجلين في لوحة تحكم معالج الوكيل أو إنشاؤها عبر API +- تستخدم الأداة بروتوكول سياق النموذج (MCP) للتواصل مع معالج الوكيل +- يتم توليد معرّفات الجلسة تلقائياً ولكن يمكن تخصيصها لاستمرارية السياق +- يتم تسجيل جميع استدعاءات الأدوات وإمكانية مراجعتها من خلال منصة معالج الوكيل +- يتم اكتشاف معاملات الأدوات ديناميكياً من واجهة برمجة تطبيقات معالج الوكيل والتحقق منها تلقائياً + +## الاستخدام + +### استخدام أداة واحدة + +إليك كيفية استخدام أداة محددة من حزمة الأدوات الخاصة بك: + +```python {2, 4-9} +from crewai import Agent, Task, Crew +from crewai_tools import MergeAgentHandlerTool + +# Create a tool for Linear issue creation +linear_create_tool = MergeAgentHandlerTool.from_tool_name( + tool_name="linear__create_issue", + tool_pack_id="134e0111-0f67-44f6-98f0-597000290bb3", + registered_user_id="91b2b905-e866-40c8-8be2-efe53827a0aa" +) + +# Create a CrewAI agent that uses the tool +project_manager = Agent( + role='Project Manager', + goal='Manage project tasks and issues efficiently', + backstory='I am an expert at tracking project work and creating actionable tasks.', + tools=[linear_create_tool], + verbose=True +) + +# Create a task for the agent +create_issue_task = Task( + description="Create a new high-priority issue in Linear titled 'Implement user authentication' with a detailed description of the requirements.", + agent=project_manager, + expected_output="Confirmation that the issue was created with its ID" +) + +# Create a crew with the agent +crew = Crew( + agents=[project_manager], + tasks=[create_issue_task], + verbose=True +) + +# Run the crew +result = crew.kickoff() +print(result) +``` + +### تحميل أدوات متعددة من حزمة أدوات + +يمكنك تحميل جميع الأدوات المتاحة من حزمة الأدوات دفعة واحدة: + +```python {2, 4-8} +from crewai import Agent, Task, Crew +from crewai_tools import MergeAgentHandlerTool + +# Load all tools from the Tool Pack +tools = MergeAgentHandlerTool.from_tool_pack( + tool_pack_id="134e0111-0f67-44f6-98f0-597000290bb3", + registered_user_id="91b2b905-e866-40c8-8be2-efe53827a0aa" +) + +# Create an agent with access to all tools +automation_expert = Agent( + role='Automation Expert', + goal='Automate workflows across multiple platforms', + backstory='I can work with any tool in the toolbox to get things done.', + tools=tools, + verbose=True +) + +automation_task = Task( + description="Check for any high-priority issues in Linear and post a summary to Slack.", + agent=automation_expert +) + +crew = Crew( + agents=[automation_expert], + tasks=[automation_task], + verbose=True +) + +result = crew.kickoff() +``` + +### تحميل أدوات محددة فقط + +تحميل الأدوات التي تحتاجها فقط: + +```python {2, 4-10} +from crewai import Agent, Task, Crew +from crewai_tools import MergeAgentHandlerTool + +# Load specific tools from the Tool Pack +selected_tools = MergeAgentHandlerTool.from_tool_pack( + tool_pack_id="134e0111-0f67-44f6-98f0-597000290bb3", + registered_user_id="91b2b905-e866-40c8-8be2-efe53827a0aa", + tool_names=["linear__create_issue", "linear__get_issues", "slack__post_message"] +) + +developer_assistant = Agent( + role='Developer Assistant', + goal='Help developers track and communicate about their work', + backstory='I help developers stay organized and keep the team informed.', + tools=selected_tools, + verbose=True +) + +daily_update_task = Task( + description="Get all issues assigned to the current user in Linear and post a summary to the #dev-updates Slack channel.", + agent=developer_assistant +) + +crew = Crew( + agents=[developer_assistant], + tasks=[daily_update_task], + verbose=True +) + +result = crew.kickoff() +``` + +## معاملات الأداة + +### طريقة `from_tool_name()` + +| المعامل | النوع | مطلوب | الافتراضي | الوصف | +|:---------|:-----|:---------|:--------|:------------| +| **tool_name** | `str` | نعم | None | اسم الأداة المحددة المراد استخدامها (مثل "linear__create_issue") | +| **tool_pack_id** | `str` | نعم | None | معرّف UUID لحزمة أدوات معالج الوكيل | +| **registered_user_id** | `str` | نعم | None | معرّف UUID أو origin_id للمستخدم المسجل | +| **base_url** | `str` | لا | "https://ah-api.merge.dev" | عنوان URL الأساسي لواجهة برمجة تطبيقات معالج الوكيل | +| **session_id** | `str` | لا | يتم توليده تلقائياً | معرّف جلسة MCP للحفاظ على السياق | + +### طريقة `from_tool_pack()` + +| المعامل | النوع | مطلوب | الافتراضي | الوصف | +|:---------|:-----|:---------|:--------|:------------| +| **tool_pack_id** | `str` | نعم | None | معرّف UUID لحزمة أدوات معالج الوكيل | +| **registered_user_id** | `str` | نعم | None | معرّف UUID أو origin_id للمستخدم المسجل | +| **tool_names** | `list[str]` | لا | None | أسماء أدوات محددة للتحميل. إذا كانت None، يتم تحميل جميع الأدوات المتاحة | +| **base_url** | `str` | لا | "https://ah-api.merge.dev" | عنوان URL الأساسي لواجهة برمجة تطبيقات معالج الوكيل | + +## متغيرات البيئة + +```bash +AGENT_HANDLER_API_KEY=your_api_key_here # Required for authentication +``` + +## الاستخدام المتقدم + +### سير عمل متعدد الوكلاء مع صلاحيات أدوات مختلفة + +```python {2, 4-20} +from crewai import Agent, Task, Crew, Process +from crewai_tools import MergeAgentHandlerTool + +# Create specialized tools for different agents +github_tools = MergeAgentHandlerTool.from_tool_pack( + tool_pack_id="134e0111-0f67-44f6-98f0-597000290bb3", + registered_user_id="91b2b905-e866-40c8-8be2-efe53827a0aa", + tool_names=["github__create_pull_request", "github__get_pull_requests"] +) + +linear_tools = MergeAgentHandlerTool.from_tool_pack( + tool_pack_id="134e0111-0f67-44f6-98f0-597000290bb3", + registered_user_id="91b2b905-e866-40c8-8be2-efe53827a0aa", + tool_names=["linear__create_issue", "linear__update_issue"] +) + +slack_tool = MergeAgentHandlerTool.from_tool_name( + tool_name="slack__post_message", + tool_pack_id="134e0111-0f67-44f6-98f0-597000290bb3", + registered_user_id="91b2b905-e866-40c8-8be2-efe53827a0aa" +) + +# Create specialized agents +code_reviewer = Agent( + role='Code Reviewer', + goal='Review pull requests and ensure code quality', + backstory='I am an expert at reviewing code changes and providing constructive feedback.', + tools=github_tools +) + +task_manager = Agent( + role='Task Manager', + goal='Track and update project tasks based on code changes', + backstory='I keep the project board up to date with the latest development progress.', + tools=linear_tools +) + +communicator = Agent( + role='Team Communicator', + goal='Keep the team informed about important updates', + backstory='I make sure everyone knows what is happening in the project.', + tools=[slack_tool] +) + +# Create sequential tasks +review_task = Task( + description="Review all open pull requests in the 'api-service' repository and identify any that need attention.", + agent=code_reviewer, + expected_output="List of pull requests that need review or have issues" +) + +update_task = Task( + description="Update Linear issues based on the pull request review findings. Mark completed PRs as done.", + agent=task_manager, + expected_output="Summary of updated Linear issues" +) + +notify_task = Task( + description="Post a summary of today's code review and task updates to the #engineering Slack channel.", + agent=communicator, + expected_output="Confirmation that the message was posted" +) + +# Create a crew with sequential processing +crew = Crew( + agents=[code_reviewer, task_manager, communicator], + tasks=[review_task, update_task, notify_task], + process=Process.sequential, + verbose=True +) + +result = crew.kickoff() +``` + +### إدارة الجلسات المخصصة + +الحفاظ على السياق عبر استدعاءات أدوات متعددة باستخدام معرّفات الجلسة: + +```python {2, 4-17} +from crewai import Agent, Task, Crew +from crewai_tools import MergeAgentHandlerTool + +# Create tools with the same session ID to maintain context +session_id = "project-sprint-planning-2024" + +create_tool = MergeAgentHandlerTool( + name="linear_create_issue", + description="Creates a new issue in Linear", + tool_name="linear__create_issue", + tool_pack_id="134e0111-0f67-44f6-98f0-597000290bb3", + registered_user_id="91b2b905-e866-40c8-8be2-efe53827a0aa", + session_id=session_id +) + +update_tool = MergeAgentHandlerTool( + name="linear_update_issue", + description="Updates an existing issue in Linear", + tool_name="linear__update_issue", + tool_pack_id="134e0111-0f67-44f6-98f0-597000290bb3", + registered_user_id="91b2b905-e866-40c8-8be2-efe53827a0aa", + session_id=session_id +) + +sprint_planner = Agent( + role='Sprint Planner', + goal='Plan and organize sprint tasks', + backstory='I help teams plan effective sprints with well-defined tasks.', + tools=[create_tool, update_tool], + verbose=True +) + +planning_task = Task( + description="Create 5 sprint tasks for the authentication feature and set their priorities based on dependencies.", + agent=sprint_planner +) + +crew = Crew( + agents=[sprint_planner], + tasks=[planning_task], + verbose=True +) + +result = crew.kickoff() +``` + +## حالات الاستخدام + +### الوصول الموحد للتكاملات +- الوصول إلى مئات أدوات الأطراف الثالثة من خلال واجهة برمجة تطبيقات موحدة واحدة دون إدارة حزم SDK متعددة +- تمكين الوكلاء من العمل مع Linear و GitHub و Slack و Notion و Jira و Asana والمزيد من نقطة تكامل واحدة +- تقليل تعقيد التكامل من خلال السماح لمعالج الوكيل بإدارة المصادقة وإصدارات API + +### سير عمل المؤسسات الآمنة +- الاستفادة من إدارة المصادقة والصلاحيات المدمجة لجميع تكاملات الأطراف الثالثة +- الحفاظ على معايير أمان المؤسسة مع التحكم المركزي في الوصول وتسجيل المراجعة +- تمكين الوكلاء من الوصول إلى أدوات الشركة دون كشف مفاتيح API أو بيانات الاعتماد في الكود + +### الأتمتة عبر المنصات +- بناء سير عمل يمتد عبر منصات متعددة (مثل إنشاء مشكلات GitHub من مهام Linear، مزامنة صفحات Notion مع Slack) +- تمكين تدفق البيانات السلس بين الأدوات المختلفة في مجموعتك التقنية +- إنشاء أتمتة ذكية تفهم السياق عبر المنصات المختلفة + +### اكتشاف الأدوات الديناميكي +- تحميل جميع الأدوات المتاحة أثناء التشغيل دون ترميز منطق التكامل بشكل ثابت +- تمكين الوكلاء من اكتشاف واستخدام أدوات جديدة عند إضافتها إلى حزمة الأدوات +- بناء وكلاء مرنة يمكنها التكيف مع تغير توفر الأدوات + +### الوصول إلى الأدوات حسب المستخدم +- يمكن لمستخدمين مختلفين الحصول على صلاحيات ومستويات وصول مختلفة للأدوات +- تمكين سير عمل متعدد المستأجرين حيث تعمل الوكلاء نيابة عن مستخدمين محددين +- الحفاظ على الإسناد والصلاحيات المناسبة لجميع إجراءات الأدوات + +## التكاملات المتاحة + +يدعم معالج وكيل Merge مئات التكاملات عبر فئات متعددة: + +- **إدارة المشاريع**: Linear، Jira، Asana، Monday.com، ClickUp +- **إدارة الكود**: GitHub، GitLab، Bitbucket +- **التواصل**: Slack، Microsoft Teams، Discord +- **التوثيق**: Notion، Confluence، Google Docs +- **إدارة علاقات العملاء**: Salesforce، HubSpot، Pipedrive +- **والمزيد...** + +قم بزيارة [وثائق معالج وكيل Merge](https://docs.ah.merge.dev/) للحصول على قائمة كاملة بالتكاملات المتاحة. + +## معالجة الأخطاء + +توفر الأداة معالجة شاملة للأخطاء: + +- **أخطاء المصادقة**: مفاتيح API غير صالحة أو مفقودة +- **أخطاء الصلاحيات**: المستخدم يفتقر إلى صلاحية الإجراء المطلوب +- **أخطاء API**: مشكلات في التواصل مع معالج الوكيل أو خدمات الأطراف الثالثة +- **أخطاء التحقق**: معاملات غير صالحة مُمررة لطرق الأداة + +يتم تغليف جميع الأخطاء في `MergeAgentHandlerToolError` لمعالجة أخطاء متسقة. diff --git a/docs/ar/tools/integration/overview.mdx b/docs/ar/tools/integration/overview.mdx new file mode 100644 index 000000000..accb39072 --- /dev/null +++ b/docs/ar/tools/integration/overview.mdx @@ -0,0 +1,76 @@ +--- +title: "نظرة عامة" +description: "ربط وكلاء CrewAI مع الأتمتة الخارجية وخدمات الذكاء الاصطناعي المُدارة" +icon: "face-smile" +mode: "wide" +--- + +تتيح أدوات التكامل لوكلائك تسليم العمل إلى منصات أتمتة أخرى وخدمات ذكاء اصطناعي مُدارة. استخدمها عندما يحتاج سير العمل إلى استدعاء نشر CrewAI موجود أو تفويض مهام متخصصة لمزودين مثل Amazon Bedrock. + +## **الأدوات المتاحة** + + + + الوصول بأمان إلى مئات أدوات الأطراف الثالثة مثل Linear و GitHub و Slack والمزيد من خلال واجهة API الموحدة من Merge. + + + + استدعاء أتمتة منصة CrewAI المباشرة، تمرير مدخلات مخصصة، واستقصاء النتائج مباشرة من وكيلك. + + + + استدعاء وكلاء Amazon Bedrock من أطقمك، إعادة استخدام حواجز حماية AWS، وبث الاستجابات مرة أخرى إلى سير العمل. + + + +## **حالات الاستخدام الشائعة** + +- **تسلسل الأتمتة**: بدء نشر CrewAI موجود من داخل طاقم أو تدفق آخر +- **تسليم المؤسسة**: توجيه المهام إلى وكلاء Bedrock التي تغلف بالفعل منطق الشركة وحواجز الحماية +- **سير العمل الهجين**: الجمع بين تفكير CrewAI والأنظمة اللاحقة التي تكشف واجهات برمجة تطبيقات الوكلاء الخاصة بها +- **المهام طويلة التشغيل**: استقصاء الأتمتة الخارجية ودمج النتائج النهائية مرة أخرى في التشغيل الحالي + +## **مثال للبدء السريع** + +```python +from crewai import Agent, Task, Crew +from crewai_tools import InvokeCrewAIAutomationTool +from crewai_tools.aws.bedrock.agents.invoke_agent_tool import BedrockInvokeAgentTool + +# External automation +analysis_automation = InvokeCrewAIAutomationTool( + crew_api_url="https://analysis-crew.acme.crewai.com", + crew_bearer_token="YOUR_BEARER_TOKEN", + crew_name="Analysis Automation", + crew_description="Runs the production-grade analysis pipeline", +) + +# Managed agent on Bedrock +knowledge_router = BedrockInvokeAgentTool( + agent_id="bedrock-agent-id", + agent_alias_id="prod", +) + +automation_strategist = Agent( + role="Automation Strategist", + goal="Orchestrate external automations and summarise their output", + backstory="You coordinate enterprise workflows and know when to delegate tasks to specialised services.", + tools=[analysis_automation, knowledge_router], + verbose=True, +) + +execute_playbook = Task( + description="Run the analysis automation and ask the Bedrock agent for executive talking points.", + agent=automation_strategist, +) + +Crew(agents=[automation_strategist], tasks=[execute_playbook]).kickoff() +``` + +## **أفضل الممارسات** + +- **تأمين بيانات الاعتماد**: قم بتخزين مفاتيح API ورموز الحامل في متغيرات البيئة أو مدير الأسرار +- **التخطيط لزمن الاستجابة**: قد تستغرق الأتمتة الخارجية وقتاً أطول - عيّن فترات استقصاء ومهلات مناسبة +- **إعادة استخدام الجلسات**: تدعم وكلاء Bedrock معرّفات الجلسة حتى تتمكن من الحفاظ على السياق عبر استدعاءات أدوات متعددة +- **التحقق من الاستجابات**: قم بتوحيد المخرجات عن بُعد (JSON، نص، رموز الحالة) قبل إعادة توجيهها إلى المهام اللاحقة +- **مراقبة الاستخدام**: تتبع سجلات المراجعة في منصة CrewAI أو AWS CloudWatch للبقاء على اطلاع بحدود الحصص والأعطال diff --git a/docs/ar/tools/overview.mdx b/docs/ar/tools/overview.mdx new file mode 100644 index 000000000..0a20c720d --- /dev/null +++ b/docs/ar/tools/overview.mdx @@ -0,0 +1,140 @@ +--- +title: "نظرة عامة على الأدوات" +description: "اكتشف مكتبة CrewAI الواسعة التي تضم أكثر من 40 أداة لتعزيز قدرات وكلاء الذكاء الاصطناعي" +icon: "toolbox" +mode: "wide" +--- + +توفر CrewAI مكتبة واسعة من الأدوات الجاهزة لتعزيز قدرات وكلائك. من معالجة الملفات إلى استخراج بيانات الويب، ومن استعلامات قواعد البيانات إلى خدمات الذكاء الاصطناعي - لدينا ما تحتاجه. + +## **فئات الأدوات** + + + + قراءة وكتابة والبحث في صيغ ملفات متنوعة بما في ذلك PDF و DOCX و JSON و CSV والمزيد. مثالية لسير عمل معالجة المستندات. + + + + استخراج البيانات من المواقع، أتمتة تفاعلات المتصفح، واستخراج المحتوى على نطاق واسع باستخدام أدوات مثل Firecrawl و Selenium والمزيد. + + + + إجراء عمليات بحث على الويب، العثور على مستودعات الكود، استكشاف محتوى YouTube، واكتشاف المعلومات عبر الإنترنت. + + + + الاتصال بقواعد بيانات SQL ومخازن المتجهات ومستودعات البيانات. الاستعلام عن MySQL و PostgreSQL و Snowflake و Qdrant و Weaviate. + + + + توليد الصور باستخدام DALL-E، معالجة مهام الرؤية، التكامل مع LangChain، بناء أنظمة RAG، والاستفادة من مفسرات الكود. + + + + التفاعل مع الخدمات السحابية بما في ذلك AWS S3 و Amazon Bedrock وخدمات التخزين السحابي والذكاء الاصطناعي الأخرى. + + + + أتمتة سير العمل مع Apify و Composio ومنصات أخرى لربط وكلائك بالخدمات الخارجية. + + + + دمج CrewAI مع الأنظمة الخارجية مثل Amazon Bedrock ومجموعة أدوات أتمتة CrewAI. + + + +## **الوصول السريع** + +هل تحتاج إلى أداة محددة؟ إليك بعض الخيارات الشائعة: + + + + تنفيذ الاسترجاع المعزز بالتوليد + + + واجهة برمجة تطبيقات بحث Google + + + قراءة أي نوع ملف + + + استخراج محتوى الويب + + + تنفيذ كود Python + + + الوصول إلى ملفات AWS S3 + + + +## **البدء** + +لاستخدام أي أداة في مشروع CrewAI الخاص بك: + +1. **استيراد** الأداة في تكوين طاقمك +2. **إضافتها** إلى قائمة أدوات وكيلك +3. **تكوين** أي مفاتيح API أو إعدادات مطلوبة + +```python +from crewai_tools import FileReadTool, SerperDevTool + +# Add tools to your agent +agent = Agent( + role="Research Analyst", + tools=[FileReadTool(), SerperDevTool()], + # ... other configuration +) +``` + +## **الحد الأقصى لعدد الاستخدامات** + +يمكنك تعيين حد أقصى لعدد استخدامات الأداة لمنع استخدامها أكثر من عدد معين من المرات. بشكل افتراضي، الحد الأقصى لعدد الاستخدامات غير محدود. + +```python +from crewai_tools import FileReadTool + +tool = FileReadTool(max_usage_count=5, ...) +``` + +هل أنت مستعد للاستكشاف؟ اختر فئة أعلاه لاكتشاف الأدوات التي تناسب حالة استخدامك! diff --git a/docs/ar/tools/search-research/arxivpapertool.mdx b/docs/ar/tools/search-research/arxivpapertool.mdx new file mode 100644 index 000000000..099aa0afe --- /dev/null +++ b/docs/ar/tools/search-research/arxivpapertool.mdx @@ -0,0 +1,111 @@ +--- +title: أداة أوراق arXiv +description: تبحث `ArxivPaperTool` في arXiv عن أوراق بحثية مطابقة لاستعلام وتقوم اختيارياً بتنزيل ملفات PDF. +icon: box-archive +mode: "wide" +--- + +# `ArxivPaperTool` + +## الوصف + +تستعلم `ArxivPaperTool` من واجهة برمجة تطبيقات arXiv عن الأوراق الأكاديمية وتُرجع نتائج مختصرة وقابلة للقراءة. يمكنها أيضاً تنزيل ملفات PDF اختيارياً إلى القرص. + +## التثبيت + +لا تحتاج هذه الأداة إلى تثبيت خاص بخلاف `crewai-tools`. + +```shell +uv add crewai-tools +``` + +لا يتطلب مفتاح API. تستخدم هذه الأداة واجهة Atom API العامة من arXiv. + +## خطوات البدء + +1. قم بتهيئة الأداة. +2. قدّم `search_query` (مثل "transformer neural network"). +3. عيّن اختيارياً `max_results` (1-100) وفعّل تنزيل PDF في المُنشئ. + +## مثال + +```python Code +from crewai import Agent, Task, Crew +from crewai_tools import ArxivPaperTool + +tool = ArxivPaperTool( + download_pdfs=False, + save_dir="./arxiv_pdfs", + use_title_as_filename=True, +) + +agent = Agent( + role="Researcher", + goal="Find relevant arXiv papers", + backstory="Expert at literature discovery", + tools=[tool], + verbose=True, +) + +task = Task( + description="Search arXiv for 'transformer neural network' and list top 5 results.", + expected_output="A concise list of 5 relevant papers with titles, links, and summaries.", + agent=agent, +) + +crew = Crew(agents=[agent], tasks=[task]) +result = crew.kickoff() +``` + +### الاستخدام المباشر (بدون وكيل) + +```python Code +from crewai_tools import ArxivPaperTool + +tool = ArxivPaperTool( + download_pdfs=True, + save_dir="./arxiv_pdfs", +) +print(tool.run(search_query="mixture of experts", max_results=3)) +``` + +## المعاملات + +### معاملات التهيئة + +- `download_pdfs` (bool, الافتراضي `False`): ما إذا كان سيتم تنزيل ملفات PDF. +- `save_dir` (str, الافتراضي `./arxiv_pdfs`): المجلد لحفظ ملفات PDF. +- `use_title_as_filename` (bool, الافتراضي `False`): استخدام عناوين الأوراق كأسماء ملفات. + +### معاملات التشغيل + +- `search_query` (str, مطلوب): استعلام البحث في arXiv. +- `max_results` (int, الافتراضي `5`, النطاق 1-100): عدد النتائج. + +## صيغة الإخراج + +تُرجع الأداة قائمة أوراق قابلة للقراءة تتضمن: +- العنوان +- الرابط (صفحة الملخص) +- مقتطف/ملخص (مقتطع) + +عند تعيين `download_pdfs=True`، يتم حفظ ملفات PDF على القرص ويشير الملخص إلى الملفات المحفوظة. + +## ملاحظات الاستخدام + +- تُرجع الأداة نصاً منسقاً مع البيانات الوصفية الرئيسية والروابط. +- عند تعيين `download_pdfs=True`، سيتم تخزين ملفات PDF في `save_dir`. + +## استكشاف الأخطاء وإصلاحها + +- إذا تلقيت انتهاء مهلة الشبكة، أعد المحاولة أو قلل `max_results`. +- أخطاء XML غير صالحة تشير إلى مشكلة في تحليل استجابة arXiv؛ جرب استعلاماً أبسط. +- قد تحدث أخطاء نظام الملفات (مثل رفض الصلاحية) عند حفظ ملفات PDF؛ تأكد من أن `save_dir` قابل للكتابة. + +## روابط ذات صلة + +- وثائق واجهة arXiv API: https://info.arxiv.org/help/api/index.html + +## معالجة الأخطاء + +- يتم التعامل مع مشكلات الشبكة و XML غير الصالح وأخطاء نظام التشغيل برسائل توضيحية. diff --git a/docs/ar/tools/search-research/bravesearchtool.mdx b/docs/ar/tools/search-research/bravesearchtool.mdx new file mode 100644 index 000000000..20e94599c --- /dev/null +++ b/docs/ar/tools/search-research/bravesearchtool.mdx @@ -0,0 +1,314 @@ +--- +title: أدوات بحث Brave +description: مجموعة أدوات للاستعلام من واجهة برمجة تطبيقات Brave Search - تغطي البحث في الويب والأخبار والصور والفيديو. +icon: searchengin +mode: "wide" +--- + +# أدوات بحث Brave + +## الوصف + +تقدم CrewAI عائلة من أدوات بحث Brave، كل منها يستهدف نقطة نهاية محددة في [واجهة برمجة تطبيقات Brave Search](https://brave.com/search/api/). بدلاً من أداة واحدة شاملة، يمكنك اختيار الأداة التي تتطابق بدقة مع نوع النتائج التي يحتاجها وكيلك: + +| الأداة | نقطة النهاية | حالة الاستخدام | +| --- | --- | --- | +| `BraveWebSearchTool` | بحث الويب | نتائج ويب عامة ومقتطفات وعناوين URL | +| `BraveNewsSearchTool` | بحث الأخبار | مقالات إخبارية حديثة وعناوين | +| `BraveImageSearchTool` | بحث الصور | نتائج صور مع الأبعاد وعناوين URL المصدر | +| `BraveVideoSearchTool` | بحث الفيديو | نتائج فيديو من جميع أنحاء الويب | +| `BraveLocalPOIsTool` | نقاط الاهتمام المحلية | العثور على نقاط الاهتمام (مثل المطاعم) | +| `BraveLocalPOIsDescriptionTool` | نقاط الاهتمام المحلية | استرجاع أوصاف المواقع المولّدة بالذكاء الاصطناعي | +| `BraveLLMContextTool` | سياق LLM | محتوى ويب مستخرج مسبقاً ومُحسَّن لوكلاء الذكاء الاصطناعي وتأريض LLM وخطوط أنابيب RAG. | + +تشترك جميع الأدوات في صنف أساسي مشترك (`BraveSearchToolBase`) يوفر سلوكاً متسقاً - تحديد المعدل، إعادة المحاولة التلقائية عند استجابات `429`، التحقق من صحة الرؤوس والمعاملات، والحفظ الاختياري في الملفات. + + + لا يزال صنف `BraveSearchTool` القديم متاحاً للتوافق مع الإصدارات السابقة، لكنه يُعتبر **قديماً** ولن يحظى بنفس مستوى الاهتمام في المستقبل. نوصي بالانتقال إلى الأدوات المحددة المدرجة أعلاه، والتي توفر تكويناً أغنى وواجهة أكثر تركيزاً. + + + + بينما يمكن استخدام العديد من الأدوات (مثل _BraveWebSearchTool_ و _BraveNewsSearchTool_ و _BraveImageSearchTool_ و _BraveVideoSearchTool_) مع اشتراك/خطة مجانية لواجهة Brave Search API، تتطلب بعض المعاملات (مثل `enable_snippets`) وبعض الأدوات (مثل _BraveLocalPOIsTool_ و _BraveLocalPOIsDescriptionTool_) خطة مدفوعة. راجع إمكانيات خطة اشتراكك للتوضيح. + + +## التثبيت + +```shell +pip install 'crewai[tools]' +``` + +## البدء + +1. **تثبيت الحزمة** - تأكد من تثبيت `crewai[tools]` في بيئة Python الخاصة بك. +2. **الحصول على مفتاح API** - سجّل في [api-dashboard.search.brave.com/login](https://api-dashboard.search.brave.com/login) لتوليد مفتاح. +3. **تعيين متغير البيئة** - خزّن مفتاحك كـ `BRAVE_API_KEY`، أو مرره مباشرة عبر معامل `api_key`. + +## أمثلة سريعة + +### بحث الويب + +```python Code +from crewai_tools import BraveWebSearchTool + +tool = BraveWebSearchTool() +results = tool.run(q="CrewAI agent framework") +print(results) +``` + +### بحث الأخبار + +```python Code +from crewai_tools import BraveNewsSearchTool + +tool = BraveNewsSearchTool() +results = tool.run(q="latest AI breakthroughs") +print(results) +``` + +### بحث الصور + +```python Code +from crewai_tools import BraveImageSearchTool + +tool = BraveImageSearchTool() +results = tool.run(q="northern lights photography") +print(results) +``` + +### بحث الفيديو + +```python Code +from crewai_tools import BraveVideoSearchTool + +tool = BraveVideoSearchTool() +results = tool.run(q="how to build AI agents") +print(results) +``` + +### أوصاف نقاط الاهتمام المحلية + +```python Code +from crewai_tools import ( + BraveWebSearchTool, + BraveLocalPOIsDescriptionTool, +) + +web_search = BraveWebSearchTool(raw=True) +poi_details = BraveLocalPOIsDescriptionTool() + +results = web_search.run(q="italian restaurants in pensacola, florida") + +if "locations" in results: + location_ids = [ loc["id"] for loc in results["locations"]["results"] ] + if location_ids: + descriptions = poi_details.run(ids=location_ids) + print(descriptions) +``` + +## معاملات المُنشئ المشتركة + +تقبل كل أداة بحث Brave المعاملات التالية عند التهيئة: + +| المعامل | النوع | الافتراضي | الوصف | +| --- | --- | --- | --- | +| `api_key` | `str \| None` | `None` | مفتاح Brave API. يعود إلى متغير البيئة `BRAVE_API_KEY`. | +| `headers` | `dict \| None` | `None` | رؤوس HTTP إضافية لإرسالها مع كل طلب (مثل `api-version`، رؤوس تحديد الموقع الجغرافي). | +| `requests_per_second` | `float` | `1.0` | الحد الأقصى لمعدل الطلبات. ستنتظر الأداة بين الاستدعاءات للبقاء ضمن هذا الحد. | +| `save_file` | `bool` | `False` | عند `True`، يتم كتابة كل استجابة في ملف `.txt` مختوم بالوقت. | +| `raw` | `bool` | `False` | عند `True`، يتم إرجاع استجابة JSON الكاملة من API دون أي تنقيح. | +| `timeout` | `int` | `30` | مهلة طلب HTTP بالثواني. | +| `country` | `str \| None` | `None` | اختصار قديم لاستهداف جغرافي (مثل `"US"`). يُفضل استخدام معامل الاستعلام `country` مباشرة. | +| `n_results` | `int` | `10` | اختصار قديم لعدد النتائج. يُفضل استخدام معامل الاستعلام `count` مباشرة. | + + + معاملات المُنشئ `country` و `n_results` موجودة للتوافق مع الإصدارات السابقة. يتم تطبيقها كقيم افتراضية عندما لا يتم تقديم معاملات الاستعلام المقابلة (`country`، `count`) وقت الاستدعاء. للكود الجديد، نوصي بتمرير `country` و `count` مباشرة كمعاملات استعلام بدلاً من ذلك. + + +## معاملات الاستعلام + +تتحقق كل أداة من صحة معاملات الاستعلام مقابل مخطط Pydantic قبل إرسال الطلب. تتنوع المعاملات قليلاً حسب نقطة النهاية - إليك ملخص لأكثرها استخداماً: + +### BraveWebSearchTool + +| المعامل | الوصف | +| --- | --- | +| `q` | **(مطلوب)** سلسلة استعلام البحث (الحد الأقصى 400 حرف). | +| `country` | رمز بلد من حرفين للاستهداف الجغرافي (مثل `"US"`). | +| `search_lang` | رمز لغة من حرفين للنتائج (مثل `"en"`). | +| `count` | الحد الأقصى لعدد النتائج المُرجعة (1-20). | +| `offset` | تخطي أول N صفحة من النتائج (0-9). | +| `safesearch` | مرشح المحتوى: `"off"` أو `"moderate"` أو `"strict"`. | +| `freshness` | مرشح الحداثة: `"pd"` (اليوم الماضي)، `"pw"` (الأسبوع الماضي)، `"pm"` (الشهر الماضي)، `"py"` (السنة الماضية)، أو نطاق تاريخ مثل `"2025-01-01to2025-06-01"`. | +| `extra_snippets` | تضمين حتى 5 مقتطفات نصية إضافية لكل نتيجة. | +| `goggles` | عنوان(عناوين) URL لـ Brave Goggles و/أو المصدر لإعادة الترتيب المخصص. | + +للمرجع الكامل للمعاملات والرؤوس، انظر [وثائق واجهة Brave Web Search API](https://api-dashboard.search.brave.com/api-reference/web/search/get). + +### BraveNewsSearchTool + +| المعامل | الوصف | +| --- | --- | +| `q` | **(مطلوب)** سلسلة استعلام البحث (الحد الأقصى 400 حرف). | +| `country` | رمز بلد من حرفين للاستهداف الجغرافي. | +| `search_lang` | رمز لغة من حرفين للنتائج. | +| `count` | الحد الأقصى لعدد النتائج المُرجعة (1-50). | +| `offset` | تخطي أول N صفحة من النتائج (0-9). | +| `safesearch` | مرشح المحتوى: `"off"` أو `"moderate"` أو `"strict"`. | +| `freshness` | مرشح الحداثة (نفس خيارات بحث الويب). | +| `goggles` | عنوان(عناوين) URL لـ Brave Goggles و/أو المصدر لإعادة الترتيب المخصص. | + +للمرجع الكامل للمعاملات والرؤوس، انظر [وثائق واجهة Brave News Search API](https://api-dashboard.search.brave.com/api-reference/news/news_search/get). + +### BraveImageSearchTool + +| المعامل | الوصف | +| --- | --- | +| `q` | **(مطلوب)** سلسلة استعلام البحث (الحد الأقصى 400 حرف). | +| `country` | رمز بلد من حرفين للاستهداف الجغرافي. | +| `search_lang` | رمز لغة من حرفين للنتائج. | +| `count` | الحد الأقصى لعدد النتائج المُرجعة (1-200). | +| `safesearch` | مرشح المحتوى: `"off"` أو `"strict"`. | +| `spellcheck` | محاولة تصحيح الأخطاء الإملائية في الاستعلام. | + +للمرجع الكامل للمعاملات والرؤوس، انظر [وثائق واجهة Brave Image Search API](https://api-dashboard.search.brave.com/api-reference/images/image_search). + +### BraveVideoSearchTool + +| المعامل | الوصف | +| --- | --- | +| `q` | **(مطلوب)** سلسلة استعلام البحث (الحد الأقصى 400 حرف). | +| `country` | رمز بلد من حرفين للاستهداف الجغرافي. | +| `search_lang` | رمز لغة من حرفين للنتائج. | +| `count` | الحد الأقصى لعدد النتائج المُرجعة (1-50). | +| `offset` | تخطي أول N صفحة من النتائج (0-9). | +| `safesearch` | مرشح المحتوى: `"off"` أو `"moderate"` أو `"strict"`. | +| `freshness` | مرشح الحداثة (نفس خيارات بحث الويب). | + +للمرجع الكامل للمعاملات والرؤوس، انظر [وثائق واجهة Brave Video Search API](https://api-dashboard.search.brave.com/api-reference/videos/video_search/get). + +### BraveLocalPOIsTool + +| المعامل | الوصف | +| --- | --- | +| `ids` | **(مطلوب)** قائمة معرّفات فريدة للمواقع المطلوبة. | +| `search_lang` | رمز لغة من حرفين للنتائج. | + +للمرجع الكامل للمعاملات والرؤوس، انظر [وثائق واجهة Brave Local POIs API](https://api-dashboard.search.brave.com/api-reference/web/local_pois). + +### BraveLocalPOIsDescriptionTool + +| المعامل | الوصف | +| --- | --- | +| `ids` | **(مطلوب)** قائمة معرّفات فريدة للمواقع المطلوبة. | + +للمرجع الكامل للمعاملات والرؤوس، انظر [وثائق واجهة Brave POI Descriptions API](https://api-dashboard.search.brave.com/api-reference/web/poi_descriptions). + +## الرؤوس المخصصة + +تدعم جميع الأدوات رؤوس طلبات HTTP مخصصة. أداة بحث الويب، على سبيل المثال، تقبل رؤوس تحديد الموقع الجغرافي للحصول على نتائج واعية بالموقع: + +```python Code +from crewai_tools import BraveWebSearchTool + +tool = BraveWebSearchTool( + headers={ + "x-loc-lat": "37.7749", + "x-loc-long": "-122.4194", + "x-loc-city": "San Francisco", + "x-loc-state": "CA", + "x-loc-country": "US", + } +) + +results = tool.run(q="best coffee shops nearby") +``` + +يمكنك أيضاً تحديث الرؤوس بعد التهيئة باستخدام طريقة `set_headers()`: + +```python Code +tool.set_headers({"api-version": "2025-01-01"}) +``` + +## الوضع الخام + +بشكل افتراضي، تقوم كل أداة بتنقيح استجابة API إلى قائمة نتائج مختصرة. إذا كنت تحتاج إلى استجابة API الكاملة غير المعالجة، فعّل الوضع الخام: + +```python Code +from crewai_tools import BraveWebSearchTool + +tool = BraveWebSearchTool(raw=True) +full_response = tool.run(q="Brave Search API") +``` + +## مثال على التكامل مع الوكيل + +إليك كيفية تزويد وكيل CrewAI بأدوات بحث Brave متعددة: + +```python Code +from crewai import Agent +from crewai.project import agent +from crewai_tools import BraveWebSearchTool, BraveNewsSearchTool + +web_search = BraveWebSearchTool() +news_search = BraveNewsSearchTool() + +@agent +def researcher(self) -> Agent: + return Agent( + config=self.agents_config["researcher"], + tools=[web_search, news_search], + ) +``` + +## مثال متقدم + +الجمع بين معاملات متعددة لبحث مستهدف: + +```python Code +from crewai_tools import BraveWebSearchTool + +tool = BraveWebSearchTool( + requests_per_second=0.5, # conservative rate limit + save_file=True, +) + +results = tool.run( + q="artificial intelligence news", + country="US", + search_lang="en", + count=5, + freshness="pm", # past month only + extra_snippets=True, +) +print(results) +``` + +## الانتقال من `BraveSearchTool` (القديمة) + +إذا كنت تستخدم حالياً `BraveSearchTool`، فالتبديل إلى الأدوات الجديدة بسيط: + +```python Code +# Before (legacy) +from crewai_tools import BraveSearchTool + +tool = BraveSearchTool(country="US", n_results=5, save_file=True) +results = tool.run(search_query="AI agents") + +# After (recommended) +from crewai_tools import BraveWebSearchTool + +tool = BraveWebSearchTool(save_file=True) +results = tool.run(q="AI agents", country="US", count=5) +``` + +الاختلافات الرئيسية: +- **الاستيراد**: استخدم `BraveWebSearchTool` (أو متغير الأخبار/الصور/الفيديو) بدلاً من `BraveSearchTool`. +- **معامل الاستعلام**: استخدم `q` بدلاً من `search_query`. (لا يزال كلا `search_query` و `query` مقبولين للراحة، لكن `q` هو المعامل المفضل.) +- **عدد النتائج**: مرر `count` كمعامل استعلام بدلاً من `n_results` عند التهيئة. +- **البلد**: مرر `country` كمعامل استعلام بدلاً من عند التهيئة. +- **مفتاح API**: يمكن الآن تمريره مباشرة عبر `api_key=` بالإضافة إلى متغير البيئة `BRAVE_API_KEY`. +- **تحديد المعدل**: قابل للتكوين عبر `requests_per_second` مع إعادة محاولة تلقائية عند استجابات `429`. + +## الخلاصة + +توفر مجموعة أدوات بحث Brave لوكلاء CrewAI وصولاً مرناً ومحدداً بنقطة النهاية إلى واجهة برمجة تطبيقات Brave Search. سواء كنت تحتاج إلى صفحات ويب أو أخبار عاجلة أو صور أو مقاطع فيديو، هناك أداة مخصصة مع معاملات مُتحقق منها ومرونة مدمجة. اختر الأداة المناسبة لحالة استخدامك، وارجع إلى [وثائق واجهة Brave Search API](https://brave.com/search/api/) للحصول على التفاصيل الكاملة حول المعاملات المتاحة وصيغ الاستجابة. diff --git a/docs/ar/tools/search-research/codedocssearchtool.mdx b/docs/ar/tools/search-research/codedocssearchtool.mdx new file mode 100644 index 000000000..a81aa5480 --- /dev/null +++ b/docs/ar/tools/search-research/codedocssearchtool.mdx @@ -0,0 +1,85 @@ +--- +title: البحث في توثيق الكود باستخدام RAG +description: أداة `CodeDocsSearchTool` هي أداة RAG (التوليد المعزز بالاسترجاع) قوية مصممة للبحث الدلالي داخل توثيق الكود. +icon: code +mode: "wide" +--- + +# `CodeDocsSearchTool` + + + **تجريبي**: لا نزال نعمل على تحسين الأدوات، لذا قد يحدث سلوك غير متوقع أو تغييرات في المستقبل. + + +## الوصف + +أداة CodeDocsSearchTool هي أداة RAG (التوليد المعزز بالاسترجاع) قوية مصممة للبحث الدلالي داخل توثيق الكود. +تتيح للمستخدمين العثور بكفاءة على معلومات أو مواضيع محددة داخل توثيق الكود. من خلال تقديم `docs_url` أثناء التهيئة، +تقتصر الأداة على البحث في موقع التوثيق المحدد. بدلاً من ذلك، بدون `docs_url` محدد، +تبحث الأداة عبر مجموعة واسعة من توثيق الكود المعروف أو المكتشف خلال تنفيذها، مما يجعلها متعددة الاستخدامات لاحتياجات البحث المختلفة في التوثيق. + +## التثبيت + +للبدء في استخدام CodeDocsSearchTool، قم أولاً بتثبيت حزمة crewai_tools عبر pip: + +```shell +pip install 'crewai[tools]' +``` + +## مثال + +استخدم CodeDocsSearchTool كما يلي لإجراء عمليات بحث داخل توثيق الكود: + +```python Code +from crewai_tools import CodeDocsSearchTool + +# To search any code documentation content +# if the URL is known or discovered during its execution: +tool = CodeDocsSearchTool() + +# OR + +# To specifically focus your search on a given documentation site +# by providing its URL: +tool = CodeDocsSearchTool(docs_url='https://docs.example.com/reference') +``` + + استبدل 'https://docs.example.com/reference' بعنوان URL الخاص بالتوثيق المستهدف + و 'How to use search tool' باستعلام البحث المناسب لاحتياجاتك. + + +## المعاملات + +يمكن استخدام المعاملات التالية لتخصيص سلوك `CodeDocsSearchTool`: + +| المعامل | النوع | الوصف | +|:---------------|:---------|:-------------------------------------------------------------------------------------------------------------------------------------| +| **docs_url** | `string` | _اختياري_. يحدد عنوان URL لتوثيق الكود المراد البحث فيه. | + +## النموذج المخصص والتضمينات + +بشكل افتراضي، تستخدم الأداة OpenAI لكل من التضمينات والتلخيص. لتخصيص النموذج، يمكنك استخدام قاموس تكوين كما يلي: + +```python Code +tool = CodeDocsSearchTool( + config=dict( + llm=dict( + provider="ollama", # or google, openai, anthropic, llama2, ... + config=dict( + model="llama2", + # temperature=0.5, + # top_p=1, + # stream=true, + ), + ), + embedder=dict( + provider="google-generativeai", # or openai, ollama, ... + config=dict( + model_name="gemini-embedding-001", + task_type="RETRIEVAL_DOCUMENT", + # title="Embeddings", + ), + ), + ) +) +``` \ No newline at end of file diff --git a/docs/ar/tools/search-research/databricks-query-tool.mdx b/docs/ar/tools/search-research/databricks-query-tool.mdx new file mode 100644 index 000000000..5384995d8 --- /dev/null +++ b/docs/ar/tools/search-research/databricks-query-tool.mdx @@ -0,0 +1,81 @@ +--- +title: أداة استعلام Databricks SQL +description: أداة `DatabricksQueryTool` تنفذ استعلامات SQL على جداول مساحة عمل Databricks. +icon: trowel-bricks +mode: "wide" +--- + +# `DatabricksQueryTool` + +## الوصف + +تنفيذ استعلامات SQL على جداول مساحة عمل Databricks باستخدام ملف تعريف CLI أو مصادقة المضيف/الرمز المباشرة. + +## التثبيت + +```shell +uv add crewai-tools[databricks-sdk] +``` + +## متغيرات البيئة + +- `DATABRICKS_CONFIG_PROFILE` أو (`DATABRICKS_HOST` + `DATABRICKS_TOKEN`) + +أنشئ رمز وصول شخصي واعثر على تفاصيل المضيف في مساحة عمل Databricks ضمن إعدادات المستخدم ← المطور. +التوثيق: https://docs.databricks.com/en/dev-tools/auth/pat.html + +## مثال + +```python Code +from crewai import Agent, Task, Crew +from crewai_tools import DatabricksQueryTool + +tool = DatabricksQueryTool( + default_catalog="main", + default_schema="default", +) + +agent = Agent( + role="Data Analyst", + goal="Query Databricks", + tools=[tool], + verbose=True, +) + +task = Task( + description="SELECT * FROM my_table LIMIT 10", + expected_output="10 rows", + agent=agent, +) + +crew = Crew( + agents=[agent], + tasks=[task], + verbose=True, +) +result = crew.kickoff() + +print(result) +``` + +## المعاملات + +- `query` (مطلوب): استعلام SQL المراد تنفيذه +- `catalog` (اختياري): تجاوز الكتالوج الافتراضي +- `db_schema` (اختياري): تجاوز المخطط الافتراضي +- `warehouse_id` (اختياري): تجاوز مستودع SQL الافتراضي +- `row_limit` (اختياري): الحد الأقصى لعدد الصفوف المُرجعة (الافتراضي: 1000) + +## القيم الافتراضية عند التهيئة + +- `default_catalog` +- `default_schema` +- `default_warehouse_id` + +### معالجة الأخطاء والنصائح + +- أخطاء المصادقة: تحقق من أن `DATABRICKS_HOST` يبدأ بـ `https://` وأن الرمز صالح. +- الصلاحيات: تأكد من أن مستودع SQL والمخطط متاحان لرمزك. +- الحدود: يجب تجنب الاستعلامات طويلة التشغيل في حلقات الـ Agent؛ أضف فلاتر/حدود. + + diff --git a/docs/ar/tools/search-research/exasearchtool.mdx b/docs/ar/tools/search-research/exasearchtool.mdx new file mode 100644 index 000000000..dfa3d32fa --- /dev/null +++ b/docs/ar/tools/search-research/exasearchtool.mdx @@ -0,0 +1,110 @@ +--- +title: "أداة بحث Exa" +description: "ابحث في الويب باستخدام Exa Search API للعثور على النتائج الأكثر صلة لأي استعلام، مع خيارات لمحتوى الصفحة الكامل والمقتطفات والملخصات." +icon: "magnifying-glass" +mode: "wide" +--- + +تتيح أداة `EXASearchTool` لوكلاء CrewAI البحث في الويب باستخدام [Exa](https://exa.ai/) search API. تُرجع النتائج الأكثر صلة لأي استعلام، مع خيارات لمحتوى الصفحة الكامل والملخصات المولّدة بالذكاء الاصطناعي. + +## التثبيت + +ثبّت حزمة أدوات CrewAI: + +```shell +pip install 'crewai[tools]' +``` + +## متغيرات البيئة + +عيّن مفتاح Exa API كمتغير بيئة: + +```bash +export EXA_API_KEY='your_exa_api_key' +``` + +احصل على مفتاح API من [لوحة تحكم Exa](https://dashboard.exa.ai/api-keys). + +## مثال على الاستخدام + +إليك كيفية استخدام `EXASearchTool` مع وكيل CrewAI: + +```python +import os +from crewai import Agent, Task, Crew +from crewai_tools import EXASearchTool + +# Initialize the tool +exa_tool = EXASearchTool() + +# Create an agent that uses the tool +researcher = Agent( + role='Research Analyst', + goal='Find the latest information on any topic', + backstory='An expert researcher who finds the most relevant and up-to-date information.', + tools=[exa_tool], + verbose=True +) + +# Create a task for the agent +research_task = Task( + description='Find the top 3 recent breakthroughs in quantum computing.', + expected_output='A summary of the top 3 breakthroughs with source URLs.', + agent=researcher +) + +# Form the crew and kick it off +crew = Crew( + agents=[researcher], + tasks=[research_task], + verbose=True +) + +result = crew.kickoff() +print(result) +``` + +## خيارات التكوين + +تقبل أداة `EXASearchTool` المعاملات التالية أثناء التهيئة: + +- `type` (str، اختياري): نوع البحث المستخدم. الافتراضي هو `"auto"`. الخيارات: `"auto"`، `"instant"`، `"fast"`، `"deep"`. +- `content` (bool، اختياري): ما إذا كان يجب تضمين محتوى الصفحة الكامل في النتائج. الافتراضي هو `False`. +- `summary` (bool، اختياري): ما إذا كان يجب تضمين ملخصات مولّدة بالذكاء الاصطناعي لكل نتيجة. يتطلب `content=True`. الافتراضي هو `False`. +- `api_key` (str، اختياري): مفتاح Exa API الخاص بك. يعود إلى متغير البيئة `EXA_API_KEY` إذا لم يتم تقديمه. +- `base_url` (str، اختياري): عنوان URL مخصص لخادم API. يعود إلى متغير البيئة `EXA_BASE_URL` إذا لم يتم تقديمه. + +عند استدعاء الأداة (أو عندما يستدعيها وكيل)، تتوفر معاملات البحث التالية: + +- `search_query` (str): **مطلوب**. سلسلة استعلام البحث. +- `start_published_date` (str، اختياري): تصفية النتائج المنشورة بعد هذا التاريخ (تنسيق ISO 8601، مثل `"2024-01-01"`). +- `end_published_date` (str، اختياري): تصفية النتائج المنشورة قبل هذا التاريخ (تنسيق ISO 8601). +- `include_domains` (list[str]، اختياري): قائمة بالنطاقات لتقييد البحث عليها. + +## الاستخدام المتقدم + +يمكنك تكوين الأداة بمعاملات مخصصة للحصول على نتائج أغنى: + +```python +# Get full page content with AI summaries +exa_tool = EXASearchTool( + content=True, + summary=True, + type="deep" +) + +# Use it in an agent +agent = Agent( + role="Deep Researcher", + goal="Conduct thorough research with full content and summaries", + tools=[exa_tool] +) +``` + +## الميزات + +- **البحث الدلالي**: العثور على نتائج بناءً على المعنى، وليس الكلمات المفتاحية فقط +- **استرجاع المحتوى الكامل**: الحصول على النص الكامل لصفحات الويب مع نتائج البحث +- **ملخصات الذكاء الاصطناعي**: الحصول على ملخصات موجزة مولّدة بالذكاء الاصطناعي لكل نتيجة +- **تصفية التاريخ**: تقييد النتائج لفترات زمنية محددة باستخدام فلاتر تاريخ النشر +- **تصفية النطاقات**: تقييد عمليات البحث على نطاقات محددة \ No newline at end of file diff --git a/docs/ar/tools/search-research/githubsearchtool.mdx b/docs/ar/tools/search-research/githubsearchtool.mdx new file mode 100644 index 000000000..5a2c0a326 --- /dev/null +++ b/docs/ar/tools/search-research/githubsearchtool.mdx @@ -0,0 +1,86 @@ +--- +title: بحث Github +description: أداة `GithubSearchTool` مصممة للبحث في المواقع وتحويلها إلى markdown نظيف أو بيانات منظمة. +icon: github +mode: "wide" +--- + +# `GithubSearchTool` + + + لا نزال نعمل على تحسين الأدوات، لذا قد يحدث سلوك غير متوقع أو تغييرات في المستقبل. + + +## الوصف + +أداة GithubSearchTool هي أداة التوليد المعزز بالاسترجاع (RAG) مصممة خصيصاً لإجراء عمليات بحث دلالية داخل مستودعات GitHub. باستخدام قدرات البحث الدلالي المتقدمة، تقوم بتصفية الكود وطلبات السحب والمشكلات والمستودعات، مما يجعلها أداة أساسية للمطورين والباحثين أو أي شخص يحتاج إلى معلومات دقيقة من GitHub. + +## التثبيت + +لاستخدام GithubSearchTool، تأكد أولاً من تثبيت حزمة crewai_tools في بيئة Python الخاصة بك: + +```shell +pip install 'crewai[tools]' +``` + +يثبّت هذا الأمر الحزمة اللازمة لتشغيل GithubSearchTool مع أي أدوات أخرى مضمنة في حزمة crewai_tools. + +احصل على رمز وصول شخصي من GitHub على https://github.com/settings/tokens (إعدادات المطور ← الرموز الدقيقة أو الرموز الكلاسيكية). + +## مثال + +إليك كيفية استخدام GithubSearchTool لإجراء عمليات بحث دلالية داخل مستودع GitHub: + +```python Code +from crewai_tools import GithubSearchTool + +# Initialize the tool for semantic searches within a specific GitHub repository +tool = GithubSearchTool( + github_repo='https://github.com/example/repo', + gh_token='your_github_personal_access_token', + content_types=['code', 'issue'] # Options: code, repo, pr, issue +) + +# OR + +# Initialize the tool for semantic searches within a specific GitHub repository, so the agent can search any repository if it learns about during its execution +tool = GithubSearchTool( + gh_token='your_github_personal_access_token', + content_types=['code', 'issue'] # Options: code, repo, pr, issue +) +``` + +## المعاملات + +- `github_repo`: عنوان URL لمستودع GitHub حيث سيتم إجراء البحث. هذا حقل إلزامي ويحدد المستودع المستهدف لبحثك. +- `gh_token`: رمز الوصول الشخصي من GitHub (PAT) المطلوب للمصادقة. يمكنك إنشاء واحد في إعدادات حساب GitHub الخاص بك ضمن إعدادات المطور > رموز الوصول الشخصية. +- `content_types`: يحدد أنواع المحتوى المراد تضمينها في بحثك. يجب تقديم قائمة بأنواع المحتوى من الخيارات التالية: `code` للبحث داخل الكود، +`repo` للبحث في المعلومات العامة للمستودع، `pr` للبحث داخل طلبات السحب، و `issue` للبحث داخل المشكلات. +هذا الحقل إلزامي ويسمح بتخصيص البحث لأنواع محتوى محددة داخل مستودع GitHub. + +## النموذج المخصص والتضمينات + +بشكل افتراضي، تستخدم الأداة OpenAI لكل من التضمينات والتلخيص. لتخصيص النموذج، يمكنك استخدام قاموس تكوين كما يلي: + +```python Code +tool = GithubSearchTool( + config=dict( + llm=dict( + provider="ollama", # or google, openai, anthropic, llama2, ... + config=dict( + model="llama2", + # temperature=0.5, + # top_p=1, + # stream=true, + ), + ), + embedder=dict( + provider="google-generativeai", # or openai, ollama, ... + config=dict( + model_name="gemini-embedding-001", + task_type="RETRIEVAL_DOCUMENT", + # title="Embeddings", + ), + ), + ) +) \ No newline at end of file diff --git a/docs/ar/tools/search-research/linkupsearchtool.mdx b/docs/ar/tools/search-research/linkupsearchtool.mdx new file mode 100644 index 000000000..3963ec454 --- /dev/null +++ b/docs/ar/tools/search-research/linkupsearchtool.mdx @@ -0,0 +1,113 @@ +--- +title: أداة بحث Linkup +description: أداة `LinkupSearchTool` تتيح الاستعلام من Linkup API للحصول على معلومات سياقية. +icon: link +mode: "wide" +--- + +# `LinkupSearchTool` + +## الوصف + +توفر أداة `LinkupSearchTool` القدرة على الاستعلام من Linkup API للحصول على معلومات سياقية واسترجاع نتائج منظمة. هذه الأداة مثالية لإثراء سير العمل بمعلومات محدّثة وموثوقة من Linkup، مما يسمح للوكلاء بالوصول إلى بيانات ذات صلة أثناء مهامهم. + +## التثبيت + +لاستخدام هذه الأداة، تحتاج إلى تثبيت Linkup SDK: + +```shell +uv add linkup-sdk +``` + +## خطوات البدء + +لاستخدام `LinkupSearchTool` بفعالية، اتبع هذه الخطوات: + +1. **مفتاح API**: احصل على مفتاح Linkup API. +2. **إعداد البيئة**: قم بإعداد بيئتك بمفتاح API. +3. **تثبيت SDK**: ثبّت Linkup SDK باستخدام الأمر أعلاه. + +## مثال + +يوضح المثال التالي كيفية تهيئة الأداة واستخدامها مع وكيل: + +```python Code +from crewai_tools import LinkupSearchTool +from crewai import Agent +import os + +# Initialize the tool with your API key +linkup_tool = LinkupSearchTool(api_key=os.getenv("LINKUP_API_KEY")) + +# Define an agent that uses the tool +@agent +def researcher(self) -> Agent: + ''' + This agent uses the LinkupSearchTool to retrieve contextual information + from the Linkup API. + ''' + return Agent( + config=self.agents_config["researcher"], + tools=[linkup_tool] + ) +``` + +## المعاملات + +تقبل أداة `LinkupSearchTool` المعاملات التالية: + +### معاملات المُنشئ +- **api_key**: مطلوب. مفتاح Linkup API الخاص بك. + +### معاملات التشغيل +- **query**: مطلوب. مصطلح أو عبارة البحث. +- **depth**: اختياري. عمق البحث. الافتراضي هو "standard". +- **output_type**: اختياري. نوع المخرجات. الافتراضي هو "searchResults". + +## الاستخدام المتقدم + +يمكنك تخصيص معاملات البحث للحصول على نتائج أكثر تحديداً: + +```python Code +# Perform a search with custom parameters +results = linkup_tool.run( + query="Women Nobel Prize Physics", + depth="deep", + output_type="searchResults" +) +``` + +## تنسيق الإرجاع + +تُرجع الأداة النتائج بالتنسيق التالي: + +```json +{ + "success": true, + "results": [ + { + "name": "Result Title", + "url": "https://example.com/result", + "content": "Content of the result..." + }, + // Additional results... + ] +} +``` + +في حالة حدوث خطأ، ستكون الاستجابة: + +```json +{ + "success": false, + "error": "Error message" +} +``` + +## معالجة الأخطاء + +تتعامل الأداة بسلاسة مع أخطاء API وتوفر ملاحظات منظمة. إذا فشل طلب API، ستُرجع الأداة قاموساً يحتوي على `success: false` ورسالة خطأ. + +## الخلاصة + +توفر أداة `LinkupSearchTool` طريقة سلسة لدمج قدرات استرجاع المعلومات السياقية من Linkup في وكلاء CrewAI. من خلال الاستفادة من هذه الأداة، يمكن للوكلاء الوصول إلى معلومات ذات صلة ومحدّثة لتعزيز اتخاذ القرارات وتنفيذ المهام. \ No newline at end of file diff --git a/docs/ar/tools/search-research/overview.mdx b/docs/ar/tools/search-research/overview.mdx new file mode 100644 index 000000000..6b73d12b5 --- /dev/null +++ b/docs/ar/tools/search-research/overview.mdx @@ -0,0 +1,94 @@ +--- +title: "نظرة عامة" +description: "إجراء عمليات بحث على الويب، والعثور على المستودعات، والبحث عن المعلومات عبر الإنترنت" +icon: "face-smile" +mode: "wide" +--- + +تتيح هذه الأدوات لوكلائك البحث في الويب، والبحث في المواضيع، والعثور على المعلومات عبر منصات متعددة بما في ذلك محركات البحث و GitHub و YouTube. + +## **الأدوات المتاحة** + + + + تكامل مع Google search API لقدرات بحث شاملة على الويب. + + + + بحث يركز على الخصوصية مع فهرس بحث Brave المستقل. + + + + بحث مدعوم بالذكاء الاصطناعي للعثور على محتوى محدد وذي صلة. + + + + بحث في الويب في الوقت الحقيقي مع فهرسة محتوى حديث. + + + + البحث في مستودعات GitHub والكود والمشكلات والتوثيق. + + + + البحث داخل مواقع ونطاقات محددة. + + + + البحث في توثيق الكود والموارد التقنية. + + + + البحث في قنوات YouTube عن محتوى ومنشئين محددين. + + + + العثور على مقاطع فيديو YouTube وتحليلها حسب الموضوع أو الكلمة المفتاحية أو المعايير. + + + + بحث شامل على الويب باستخدام Tavily search API المدعوم بالذكاء الاصطناعي. + + + + استخراج محتوى منظم من صفحات الويب باستخدام Tavily API. + + + + البحث في arXiv وتنزيل ملفات PDF اختيارياً. + + + + بحث Google عبر SerpApi مع نتائج منظمة. + + + + استعلامات Google Shopping عبر SerpApi. + + + +## **حالات الاستخدام الشائعة** + +- **أبحاث السوق**: البحث عن اتجاهات الصناعة وتحليل المنافسين +- **اكتشاف المحتوى**: العثور على مقالات وفيديوهات وموارد ذات صلة +- **بحث الكود**: البحث في المستودعات والتوثيق عن حلول +- **توليد العملاء المحتملين**: البحث عن الشركات والأفراد +- **البحث الأكاديمي**: العثور على مقالات علمية وأوراق تقنية + +```python +from crewai_tools import SerperDevTool, GitHubSearchTool, YoutubeVideoSearchTool, TavilySearchTool, TavilyExtractorTool + +# Create research tools +web_search = SerperDevTool() +code_search = GitHubSearchTool() +video_research = YoutubeVideoSearchTool() +tavily_search = TavilySearchTool() +content_extractor = TavilyExtractorTool() + +# Add to your agent +agent = Agent( + role="Research Analyst", + tools=[web_search, code_search, video_research, tavily_search, content_extractor], + goal="Gather comprehensive information on any topic" +) +``` \ No newline at end of file diff --git a/docs/ar/tools/search-research/serpapi-googlesearchtool.mdx b/docs/ar/tools/search-research/serpapi-googlesearchtool.mdx new file mode 100644 index 000000000..89a5e27f8 --- /dev/null +++ b/docs/ar/tools/search-research/serpapi-googlesearchtool.mdx @@ -0,0 +1,66 @@ +--- +title: أداة بحث Google عبر SerpApi +description: أداة `SerpApiGoogleSearchTool` تنفذ عمليات بحث Google باستخدام خدمة SerpApi. +icon: google +mode: "wide" +--- + +# `SerpApiGoogleSearchTool` + +## الوصف + +استخدم `SerpApiGoogleSearchTool` لتشغيل عمليات بحث Google باستخدام SerpApi واسترجاع نتائج منظمة. يتطلب مفتاح SerpApi API. + +## التثبيت + +```shell +uv add crewai-tools[serpapi] +``` + +## متغيرات البيئة + +- `SERPAPI_API_KEY` (مطلوب): مفتاح API لـ SerpApi. أنشئ واحداً على https://serpapi.com/ (طبقة مجانية متاحة). + +## مثال + +```python Code +from crewai import Agent, Task, Crew +from crewai_tools import SerpApiGoogleSearchTool + +tool = SerpApiGoogleSearchTool() + +agent = Agent( + role="Researcher", + goal="Answer questions using Google search", + backstory="Search specialist", + tools=[tool], + verbose=True, +) + +task = Task( + description="Search for the latest CrewAI releases", + expected_output="A concise list of relevant results with titles and links", + agent=agent, +) + +crew = Crew(agents=[agent], tasks=[task]) +result = crew.kickoff() +``` + +## ملاحظات + +- عيّن `SERPAPI_API_KEY` في البيئة. أنشئ مفتاحاً على https://serpapi.com/ +- انظر أيضاً Google Shopping عبر SerpApi: `/ar/tools/search-research/serpapi-googleshoppingtool` + +## المعاملات + +### معاملات التشغيل + +- `search_query` (str، مطلوب): استعلام Google. +- `location` (str، اختياري): معامل الموقع الجغرافي. + +## ملاحظات + +- هذه الأداة تغلّف SerpApi وتُرجع نتائج بحث منظمة. + + diff --git a/docs/ar/tools/search-research/serpapi-googleshoppingtool.mdx b/docs/ar/tools/search-research/serpapi-googleshoppingtool.mdx new file mode 100644 index 000000000..28a823f2d --- /dev/null +++ b/docs/ar/tools/search-research/serpapi-googleshoppingtool.mdx @@ -0,0 +1,62 @@ +--- +title: أداة تسوق Google عبر SerpApi +description: أداة `SerpApiGoogleShoppingTool` تبحث في نتائج Google Shopping باستخدام SerpApi. +icon: cart-shopping +mode: "wide" +--- + +# `SerpApiGoogleShoppingTool` + +## الوصف + +استفد من `SerpApiGoogleShoppingTool` للاستعلام من Google Shopping عبر SerpApi واسترجاع نتائج موجّهة للمنتجات. + +## التثبيت + +```shell +uv add crewai-tools[serpapi] +``` + +## متغيرات البيئة + +- `SERPAPI_API_KEY` (مطلوب): مفتاح API لـ SerpApi. أنشئ واحداً على https://serpapi.com/ (طبقة مجانية متاحة). + +## مثال + +```python Code +from crewai import Agent, Task, Crew +from crewai_tools import SerpApiGoogleShoppingTool + +tool = SerpApiGoogleShoppingTool() + +agent = Agent( + role="Shopping Researcher", + goal="Find relevant products", + backstory="Expert in product search", + tools=[tool], + verbose=True, +) + +task = Task( + description="Search Google Shopping for 'wireless noise-canceling headphones'", + expected_output="Top relevant products with titles and links", + agent=agent, +) + +crew = Crew(agents=[agent], tasks=[task]) +result = crew.kickoff() +``` + +## ملاحظات + +- عيّن `SERPAPI_API_KEY` في البيئة. أنشئ مفتاحاً على https://serpapi.com/ +- انظر أيضاً بحث Google على الويب عبر SerpApi: `/ar/tools/search-research/serpapi-googlesearchtool` + +## المعاملات + +### معاملات التشغيل + +- `search_query` (str، مطلوب): استعلام البحث عن المنتجات. +- `location` (str، اختياري): معامل الموقع الجغرافي. + + diff --git a/docs/ar/tools/search-research/serperdevtool.mdx b/docs/ar/tools/search-research/serperdevtool.mdx new file mode 100644 index 000000000..63d03bea3 --- /dev/null +++ b/docs/ar/tools/search-research/serperdevtool.mdx @@ -0,0 +1,107 @@ +--- +title: بحث Google عبر Serper +description: أداة `SerperDevTool` مصممة للبحث في الإنترنت وإرجاع النتائج الأكثر صلة. +icon: google +mode: "wide" +--- + +# `SerperDevTool` + +## الوصف + +هذه الأداة مصممة لإجراء بحث دلالي عن استعلام محدد من محتوى نصي عبر الإنترنت. تستخدم [serper.dev](https://serper.dev) API +لجلب وعرض نتائج البحث الأكثر صلة بناءً على الاستعلام المقدم من المستخدم. + +## التثبيت + +لاستخدام `SerperDevTool` بفعالية، اتبع هذه الخطوات: + +1. **تثبيت الحزمة**: تأكد من تثبيت حزمة `crewai[tools]` في بيئة Python الخاصة بك. +2. **الحصول على مفتاح API**: احصل على مفتاح `serper.dev` API على https://serper.dev/ (طبقة مجانية متاحة). +3. **تكوين البيئة**: خزّن مفتاح API الذي حصلت عليه في متغير بيئة باسم `SERPER_API_KEY` لتسهيل استخدامه بواسطة الأداة. + +لدمج هذه الأداة في مشروعك، اتبع تعليمات التثبيت أدناه: + +```shell +pip install 'crewai[tools]' +``` + +## مثال + +يوضح المثال التالي كيفية تهيئة الأداة وتنفيذ بحث باستعلام معين: + +```python Code +from crewai_tools import SerperDevTool + +# Initialize the tool for internet searching capabilities +tool = SerperDevTool() +``` + +## المعاملات + +تأتي أداة `SerperDevTool` مع عدة معاملات تُمرّر إلى API: + +- **search_url**: نقطة نهاية URL لـ search API. (الافتراضي هو `https://google.serper.dev/search`) + +- **country**: اختياري. تحديد البلد لنتائج البحث. +- **location**: اختياري. تحديد الموقع لنتائج البحث. +- **locale**: اختياري. تحديد اللغة المحلية لنتائج البحث. +- **n_results**: عدد نتائج البحث المُرجعة. الافتراضي هو `10`. + +يمكن العثور على قيم `country` و `location` و `locale` و `search_url` في [Serper Playground](https://serper.dev/playground). + +## مثال مع المعاملات + +إليك مثالاً يوضح كيفية استخدام الأداة مع معاملات إضافية: + +```python Code +from crewai_tools import SerperDevTool + +tool = SerperDevTool( + search_url="https://google.serper.dev/scholar", + n_results=2, +) + +print(tool.run(search_query="ChatGPT")) + +# Using Tool: Search the internet + +# Search results: Title: Role of chat gpt in public health +# Link: https://link.springer.com/article/10.1007/s10439-023-03172-7 +# Snippet: … ChatGPT in public health. In this overview, we will examine the potential uses of ChatGPT in +# --- +# Title: Potential use of chat gpt in global warming +# Link: https://link.springer.com/article/10.1007/s10439-023-03171-8 +# Snippet: … as ChatGPT, have the potential to play a critical role in advancing our understanding of climate +# --- + +``` + +```python Code +from crewai_tools import SerperDevTool + +tool = SerperDevTool( + country="fr", + locale="fr", + location="Paris, Paris, Ile-de-France, France", + n_results=2, +) + +print(tool.run(search_query="Jeux Olympiques")) + +# Using Tool: Search the internet + +# Search results: Title: Jeux Olympiques de Paris 2024 - Actualités, calendriers, résultats +# Link: https://olympics.com/fr/paris-2024 +# Snippet: Quels sont les sports présents aux Jeux Olympiques de Paris 2024 ? · Athlétisme · Aviron · Badminton · Basketball · Basketball 3x3 · Boxe · Breaking · Canoë ... +# --- +# Title: Billetterie Officielle de Paris 2024 - Jeux Olympiques et Paralympiques +# Link: https://tickets.paris2024.org/ +# Snippet: Achetez vos billets exclusivement sur le site officiel de la billetterie de Paris 2024 pour participer au plus grand événement sportif au monde. +# --- +``` + +## الخلاصة + +من خلال دمج `SerperDevTool` في مشاريع Python، يكتسب المستخدمون القدرة على إجراء عمليات بحث فورية وذات صلة عبر الإنترنت مباشرة من تطبيقاتهم. +تسمح المعاملات المحدّثة بنتائج بحث أكثر تخصيصاً وتوطيناً. من خلال الالتزام بإرشادات الإعداد والاستخدام المقدمة، يصبح دمج هذه الأداة في المشاريع سلساً ومباشراً. \ No newline at end of file diff --git a/docs/ar/tools/search-research/tavilyextractortool.mdx b/docs/ar/tools/search-research/tavilyextractortool.mdx new file mode 100644 index 000000000..e251f7e9a --- /dev/null +++ b/docs/ar/tools/search-research/tavilyextractortool.mdx @@ -0,0 +1,140 @@ +--- +title: "أداة استخراج Tavily" +description: "استخراج محتوى منظم من صفحات الويب باستخدام Tavily API" +icon: square-poll-horizontal +mode: "wide" +--- + +تتيح أداة `TavilyExtractorTool` لوكلاء CrewAI استخراج محتوى منظم من صفحات الويب باستخدام Tavily API. يمكنها معالجة عناوين URL مفردة أو قوائم من عناوين URL وتوفر خيارات للتحكم في عمق الاستخراج وتضمين الصور. + +## التثبيت + +لاستخدام `TavilyExtractorTool`، تحتاج إلى تثبيت مكتبة `tavily-python`: + +```shell +pip install 'crewai[tools]' tavily-python +``` + +تحتاج أيضاً إلى تعيين مفتاح Tavily API كمتغير بيئة: + +```bash +export TAVILY_API_KEY='your-tavily-api-key' +``` + +## مثال على الاستخدام + +إليك كيفية تهيئة واستخدام `TavilyExtractorTool` مع وكيل CrewAI: + +```python +import os +from crewai import Agent, Task, Crew +from crewai_tools import TavilyExtractorTool + +# Ensure TAVILY_API_KEY is set in your environment +# os.environ["TAVILY_API_KEY"] = "YOUR_API_KEY" + +# Initialize the tool +tavily_tool = TavilyExtractorTool() + +# Create an agent that uses the tool +extractor_agent = Agent( + role='Web Content Extractor', + goal='Extract key information from specified web pages', + backstory='You are an expert at extracting relevant content from websites using the Tavily API.', + tools=[tavily_tool], + verbose=True +) + +# Define a task for the agent +extract_task = Task( + description='Extract the main content from the URL https://example.com using basic extraction depth.', + expected_output='A JSON string containing the extracted content from the URL.', + agent=extractor_agent +) + +# Create and run the crew +crew = Crew( + agents=[extractor_agent], + tasks=[extract_task], + verbose=2 +) + +result = crew.kickoff() +print(result) +``` + +## خيارات التكوين + +تقبل أداة `TavilyExtractorTool` المعاملات التالية: + +- `urls` (Union[List[str], str]): **مطلوب**. سلسلة URL واحدة أو قائمة من سلاسل URL لاستخراج البيانات منها. +- `include_images` (Optional[bool]): ما إذا كان يجب تضمين الصور في نتائج الاستخراج. الافتراضي هو `False`. +- `extract_depth` (Literal["basic", "advanced"]): عمق الاستخراج. استخدم `"basic"` للاستخراج السريع السطحي أو `"advanced"` للاستخراج الأكثر شمولاً. الافتراضي هو `"basic"`. +- `timeout` (int): الحد الأقصى للوقت بالثواني لانتظار إكمال طلب الاستخراج. الافتراضي هو `60`. + +## الاستخدام المتقدم + +### عناوين URL متعددة مع استخراج متقدم + +```python +# Example with multiple URLs and advanced extraction +multi_extract_task = Task( + description='Extract content from https://example.com and https://anotherexample.org using advanced extraction.', + expected_output='A JSON string containing the extracted content from both URLs.', + agent=extractor_agent +) + +# Configure the tool with custom parameters +custom_extractor = TavilyExtractorTool( + extract_depth='advanced', + include_images=True, + timeout=120 +) + +agent_with_custom_tool = Agent( + role="Advanced Content Extractor", + goal="Extract comprehensive content with images", + tools=[custom_extractor] +) +``` + +### معاملات الأداة + +يمكنك تخصيص سلوك الأداة عن طريق تعيين المعاملات أثناء التهيئة: + +```python +# Initialize with custom configuration +extractor_tool = TavilyExtractorTool( + extract_depth='advanced', # More comprehensive extraction + include_images=True, # Include image results + timeout=90 # Custom timeout +) +``` + +## الميزات + +- **عنوان URL واحد أو متعدد**: استخراج المحتوى من عنوان URL واحد أو معالجة عناوين URL متعددة في طلب واحد +- **عمق قابل للتكوين**: الاختيار بين أوضاع الاستخراج الأساسي (السريع) والمتقدم (الشامل) +- **دعم الصور**: تضمين الصور اختيارياً في نتائج الاستخراج +- **مخرجات منظمة**: إرجاع JSON منسّق يحتوي على المحتوى المستخرج +- **معالجة الأخطاء**: معالجة قوية لمهلات الشبكة وأخطاء الاستخراج + +## تنسيق الاستجابة + +تُرجع الأداة سلسلة JSON تمثل البيانات المنظمة المستخرجة من عنوان (عناوين) URL المقدمة. يعتمد الهيكل الدقيق على محتوى الصفحات و `extract_depth` المستخدم. + +تشمل عناصر الاستجابة الشائعة: +- **Title**: عنوان الصفحة +- **Content**: المحتوى النصي الرئيسي للصفحة +- **Images**: عناوين URL للصور والبيانات الوصفية (عند `include_images=True`) +- **Metadata**: معلومات إضافية عن الصفحة مثل المؤلف والوصف وغيرها + +## حالات الاستخدام + +- **تحليل المحتوى**: استخراج وتحليل المحتوى من مواقع المنافسين +- **البحث**: جمع بيانات منظمة من مصادر متعددة للتحليل +- **ترحيل المحتوى**: استخراج المحتوى من المواقع الحالية للترحيل +- **المراقبة**: الاستخراج المنتظم للمحتوى لاكتشاف التغييرات +- **جمع البيانات**: الاستخراج المنهجي للمعلومات من مصادر الويب + +راجع [توثيق Tavily API](https://docs.tavily.com/docs/tavily-api/python-sdk#extract) للحصول على معلومات مفصلة حول هيكل الاستجابة والخيارات المتاحة. \ No newline at end of file diff --git a/docs/ar/tools/search-research/tavilysearchtool.mdx b/docs/ar/tools/search-research/tavilysearchtool.mdx new file mode 100644 index 000000000..e7ef712e4 --- /dev/null +++ b/docs/ar/tools/search-research/tavilysearchtool.mdx @@ -0,0 +1,125 @@ +--- +title: "أداة بحث Tavily" +description: "إجراء عمليات بحث شاملة على الويب باستخدام Tavily Search API" +icon: "magnifying-glass" +mode: "wide" +--- + +توفر أداة `TavilySearchTool` واجهة لـ Tavily Search API، مما يتيح لوكلاء CrewAI إجراء عمليات بحث شاملة على الويب. تسمح بتحديد عمق البحث والمواضيع والنطاقات الزمنية والنطاقات المضمنة/المستبعدة، وما إذا كان يجب تضمين إجابات مباشرة أو محتوى خام أو صور في النتائج. + +## التثبيت + +لاستخدام `TavilySearchTool`، تحتاج إلى تثبيت مكتبة `tavily-python`: + +```shell +pip install 'crewai[tools]' tavily-python +``` + +## متغيرات البيئة + +تأكد من تعيين مفتاح Tavily API كمتغير بيئة: + +```bash +export TAVILY_API_KEY='your_tavily_api_key' +``` + +احصل على مفتاح API على https://app.tavily.com/ (سجّل، ثم أنشئ مفتاحاً). + +## مثال على الاستخدام + +إليك كيفية تهيئة واستخدام `TavilySearchTool` مع وكيل CrewAI: + +```python +import os +from crewai import Agent, Task, Crew +from crewai_tools import TavilySearchTool + +# Ensure the TAVILY_API_KEY environment variable is set +# os.environ["TAVILY_API_KEY"] = "YOUR_TAVILY_API_KEY" + +# Initialize the tool +tavily_tool = TavilySearchTool() + +# Create an agent that uses the tool +researcher = Agent( + role='Market Researcher', + goal='Find information about the latest AI trends', + backstory='An expert market researcher specializing in technology.', + tools=[tavily_tool], + verbose=True +) + +# Create a task for the agent +research_task = Task( + description='Search for the top 3 AI trends in 2024.', + expected_output='A JSON report summarizing the top 3 AI trends found.', + agent=researcher +) + +# Form the crew and kick it off +crew = Crew( + agents=[researcher], + tasks=[research_task], + verbose=2 +) + +result = crew.kickoff() +print(result) +``` + +## خيارات التكوين + +تقبل أداة `TavilySearchTool` المعاملات التالية أثناء التهيئة أو عند استدعاء طريقة `run`: + +- `query` (str): **مطلوب**. سلسلة استعلام البحث. +- `search_depth` (Literal["basic", "advanced"]، اختياري): عمق البحث. الافتراضي هو `"basic"`. +- `topic` (Literal["general", "news", "finance"]، اختياري): الموضوع لتركيز البحث عليه. الافتراضي هو `"general"`. +- `time_range` (Literal["day", "week", "month", "year"]، اختياري): النطاق الزمني للبحث. الافتراضي هو `None`. +- `days` (int، اختياري): عدد الأيام للبحث للخلف. ذو صلة إذا لم يتم تعيين `time_range`. الافتراضي هو `7`. +- `max_results` (int، اختياري): الحد الأقصى لعدد نتائج البحث المُرجعة. الافتراضي هو `5`. +- `include_domains` (Sequence[str]، اختياري): قائمة بالنطاقات لإعطائها الأولوية في البحث. الافتراضي هو `None`. +- `exclude_domains` (Sequence[str]، اختياري): قائمة بالنطاقات لاستبعادها من البحث. الافتراضي هو `None`. +- `include_answer` (Union[bool, Literal["basic", "advanced"]]، اختياري): ما إذا كان يجب تضمين إجابة مباشرة مُركّبة من نتائج البحث. الافتراضي هو `False`. +- `include_raw_content` (bool، اختياري): ما إذا كان يجب تضمين محتوى HTML الخام للصفحات المبحوث عنها. الافتراضي هو `False`. +- `include_images` (bool، اختياري): ما إذا كان يجب تضمين نتائج الصور. الافتراضي هو `False`. +- `timeout` (int، اختياري): مهلة الطلب بالثواني. الافتراضي هو `60`. + +## الاستخدام المتقدم + +يمكنك تكوين الأداة بمعاملات مخصصة: + +```python +# Example: Initialize with specific parameters +custom_tavily_tool = TavilySearchTool( + search_depth='advanced', + max_results=10, + include_answer=True +) + +# The agent will use these defaults +agent_with_custom_tool = Agent( + role="Advanced Researcher", + goal="Conduct detailed research with comprehensive results", + tools=[custom_tavily_tool] +) +``` + +## الميزات + +- **بحث شامل**: الوصول إلى فهرس بحث Tavily القوي +- **عمق قابل للتكوين**: الاختيار بين أوضاع البحث الأساسي والمتقدم +- **تصفية المواضيع**: تركيز عمليات البحث على المواضيع العامة أو الأخبار أو المالية +- **التحكم في النطاق الزمني**: تقييد النتائج لفترات زمنية محددة +- **التحكم في النطاقات**: تضمين أو استبعاد نطاقات محددة +- **إجابات مباشرة**: الحصول على إجابات مُركّبة من نتائج البحث +- **تصفية المحتوى**: منع مشاكل نافذة السياق مع اقتطاع المحتوى التلقائي + +## تنسيق الاستجابة + +تُرجع الأداة نتائج البحث كسلسلة JSON تحتوي على: +- نتائج بحث مع عناوين وعناوين URL ومقتطفات محتوى +- إجابات مباشرة اختيارية للاستعلامات +- نتائج صور اختيارية +- محتوى HTML خام اختياري (عند التفعيل) + +يتم اقتطاع المحتوى لكل نتيجة تلقائياً لمنع مشاكل نافذة السياق مع الحفاظ على المعلومات الأكثر صلة. \ No newline at end of file diff --git a/docs/ar/tools/search-research/websitesearchtool.mdx b/docs/ar/tools/search-research/websitesearchtool.mdx new file mode 100644 index 000000000..f332f329c --- /dev/null +++ b/docs/ar/tools/search-research/websitesearchtool.mdx @@ -0,0 +1,78 @@ +--- +title: البحث في المواقع باستخدام RAG +description: أداة `WebsiteSearchTool` مصممة لإجراء بحث RAG (التوليد المعزز بالاسترجاع) داخل محتوى موقع ويب. +icon: globe-stand +mode: "wide" +--- + +# `WebsiteSearchTool` + + + أداة WebsiteSearchTool حالياً في مرحلة تجريبية. نحن نعمل بنشاط على دمج هذه الأداة في مجموعة عروضنا وسنقوم بتحديث التوثيق وفقاً لذلك. + + +## الوصف + +أداة WebsiteSearchTool مصممة كمفهوم لإجراء عمليات بحث دلالية داخل محتوى المواقع. +تهدف إلى الاستفادة من نماذج التعلم الآلي المتقدمة مثل التوليد المعزز بالاسترجاع (RAG) للتنقل واستخراج المعلومات من عناوين URL المحددة بكفاءة. +تهدف هذه الأداة إلى توفير المرونة، مما يسمح للمستخدمين بإجراء عمليات بحث عبر أي موقع أو التركيز على مواقع محددة ذات اهتمام. +يرجى ملاحظة أن تفاصيل التنفيذ الحالية لأداة WebsiteSearchTool قيد التطوير، وقد لا تكون وظائفها كما هو موصوف متاحة بعد. + +## التثبيت + +لتحضير بيئتك لعندما تصبح أداة WebsiteSearchTool متاحة، يمكنك تثبيت الحزمة الأساسية بـ: + +```shell +pip install 'crewai[tools]' +``` + +يثبّت هذا الأمر التبعيات اللازمة لضمان أنه بمجرد دمج الأداة بالكامل، يمكن للمستخدمين البدء في استخدامها فوراً. + +## مثال على الاستخدام + +فيما يلي أمثلة على كيفية استخدام أداة WebsiteSearchTool في سيناريوهات مختلفة. يرجى ملاحظة أن هذه الأمثلة توضيحية وتمثل وظائف مخططة: + +```python Code +from crewai_tools import WebsiteSearchTool + +# Example of initiating tool that agents can use +# to search across any discovered websites +tool = WebsiteSearchTool() + +# Example of limiting the search to the content of a specific website, +# so now agents can only search within that website +tool = WebsiteSearchTool(website='https://example.com') +``` + +## المعاملات + +- `website`: معامل اختياري مخصص لتحديد عنوان URL للموقع لعمليات البحث المركزة. هذا المعامل مصمم لتعزيز مرونة الأداة من خلال السماح بعمليات بحث موجّهة عند الحاجة. + +## خيارات التخصيص + +بشكل افتراضي، تستخدم الأداة OpenAI لكل من التضمينات والتلخيص. لتخصيص النموذج، يمكنك استخدام قاموس تكوين كما يلي: + + +```python Code +tool = WebsiteSearchTool( + config=dict( + llm=dict( + provider="ollama", # or google, openai, anthropic, llama2, ... + config=dict( + model="llama2", + # temperature=0.5, + # top_p=1, + # stream=true, + ), + ), + embedder=dict( + provider="google-generativeai", # or openai, ollama, ... + config=dict( + model_name="gemini-embedding-001", + task_type="RETRIEVAL_DOCUMENT", + # title="Embeddings", + ), + ), + ) +) +``` \ No newline at end of file diff --git a/docs/ar/tools/search-research/youtubechannelsearchtool.mdx b/docs/ar/tools/search-research/youtubechannelsearchtool.mdx new file mode 100644 index 000000000..a88e87d01 --- /dev/null +++ b/docs/ar/tools/search-research/youtubechannelsearchtool.mdx @@ -0,0 +1,195 @@ +--- +title: البحث في قنوات YouTube باستخدام RAG +description: أداة `YoutubeChannelSearchTool` مصممة لإجراء بحث RAG (التوليد المعزز بالاسترجاع) داخل محتوى قناة YouTube. +icon: youtube +mode: "wide" +--- + +# `YoutubeChannelSearchTool` + + + لا نزال نعمل على تحسين الأدوات، لذا قد يحدث سلوك غير متوقع أو تغييرات في المستقبل. + + +## الوصف + +هذه الأداة مصممة لإجراء عمليات بحث دلالية داخل محتوى قناة YouTube محددة. +من خلال الاستفادة من منهجية RAG (التوليد المعزز بالاسترجاع)، توفر نتائج بحث ذات صلة، +مما يجعلها لا تقدر بثمن لاستخراج المعلومات أو العثور على محتوى محدد دون الحاجة إلى تصفح الفيديوهات يدوياً. +تبسّط عملية البحث داخل قنوات YouTube، مما يخدم الباحثين ومنشئي المحتوى والمشاهدين الذين يبحثون عن معلومات أو مواضيع محددة. + +## التثبيت + +لاستخدام YoutubeChannelSearchTool، يجب تثبيت حزمة `crewai_tools`. نفّذ الأمر التالي في الطرفية للتثبيت: + +```shell +pip install 'crewai[tools]' +``` + +## مثال + +يوضح المثال التالي كيفية استخدام `YoutubeChannelSearchTool` مع وكيل CrewAI: + +```python Code +from crewai import Agent, Task, Crew +from crewai_tools import YoutubeChannelSearchTool + +# Initialize the tool for general YouTube channel searches +youtube_channel_tool = YoutubeChannelSearchTool() + +# Define an agent that uses the tool +channel_researcher = Agent( + role="Channel Researcher", + goal="Extract relevant information from YouTube channels", + backstory="An expert researcher who specializes in analyzing YouTube channel content.", + tools=[youtube_channel_tool], + verbose=True, +) + +# Example task to search for information in a specific channel +research_task = Task( + description="Search for information about machine learning tutorials in the YouTube channel {youtube_channel_handle}", + expected_output="A summary of the key machine learning tutorials available on the channel.", + agent=channel_researcher, +) + +# Create and run the crew +crew = Crew(agents=[channel_researcher], tasks=[research_task]) +result = crew.kickoff(inputs={"youtube_channel_handle": "@exampleChannel"}) +``` + +يمكنك أيضاً تهيئة الأداة بمعرّف قناة YouTube محدد: + +```python Code +# Initialize the tool with a specific YouTube channel handle +youtube_channel_tool = YoutubeChannelSearchTool( + youtube_channel_handle='@exampleChannel' +) + +# Define an agent that uses the tool +channel_researcher = Agent( + role="Channel Researcher", + goal="Extract relevant information from a specific YouTube channel", + backstory="An expert researcher who specializes in analyzing YouTube channel content.", + tools=[youtube_channel_tool], + verbose=True, +) +``` + +## المعاملات + +تقبل أداة `YoutubeChannelSearchTool` المعاملات التالية: + +- **youtube_channel_handle**: اختياري. معرّف قناة YouTube للبحث داخلها. إذا تم تقديمه أثناء التهيئة، لن يحتاج الوكيل إلى تحديده عند استخدام الأداة. إذا لم يبدأ المعرّف بـ '@'، سيتم إضافته تلقائياً. +- **config**: اختياري. تكوين لنظام RAG الأساسي، بما في ذلك إعدادات LLM والتضمينات. +- **summarize**: اختياري. ما إذا كان يجب تلخيص المحتوى المسترجع. الافتراضي هو `False`. + +عند استخدام الأداة مع وكيل، سيحتاج الوكيل إلى تقديم: + +- **search_query**: مطلوب. استعلام البحث للعثور على معلومات ذات صلة في محتوى القناة. +- **youtube_channel_handle**: مطلوب فقط إذا لم يتم تقديمه أثناء التهيئة. معرّف قناة YouTube للبحث داخلها. + +## النموذج المخصص والتضمينات + +بشكل افتراضي، تستخدم الأداة OpenAI لكل من التضمينات والتلخيص. لتخصيص النموذج، يمكنك استخدام قاموس تكوين كما يلي: + +```python Code +youtube_channel_tool = YoutubeChannelSearchTool( + config=dict( + llm=dict( + provider="ollama", # or google, openai, anthropic, llama2, ... + config=dict( + model="llama2", + # temperature=0.5, + # top_p=1, + # stream=true, + ), + ), + embedder=dict( + provider="google-generativeai", # or openai, ollama, ... + config=dict( + model_name="gemini-embedding-001", + task_type="RETRIEVAL_DOCUMENT", + # title="Embeddings", + ), + ), + ) +) +``` + +## مثال على التكامل مع الوكيل + +إليك مثالاً أكثر تفصيلاً لكيفية دمج `YoutubeChannelSearchTool` مع وكيل CrewAI: + +```python Code +from crewai import Agent, Task, Crew +from crewai_tools import YoutubeChannelSearchTool + +# Initialize the tool +youtube_channel_tool = YoutubeChannelSearchTool() + +# Define an agent that uses the tool +channel_researcher = Agent( + role="Channel Researcher", + goal="Extract and analyze information from YouTube channels", + backstory="""You are an expert channel researcher who specializes in extracting + and analyzing information from YouTube channels. You have a keen eye for detail + and can quickly identify key points and insights from video content across an entire channel.""", + tools=[youtube_channel_tool], + verbose=True, +) + +# Create a task for the agent +research_task = Task( + description=""" + Search for information about data science projects and tutorials + in the YouTube channel {youtube_channel_handle}. + + Focus on: + 1. Key data science techniques covered + 2. Popular tutorial series + 3. Most viewed or recommended videos + + Provide a comprehensive summary of these points. + """, + expected_output="A detailed summary of data science content available on the channel.", + agent=channel_researcher, +) + +# Run the task +crew = Crew(agents=[channel_researcher], tasks=[research_task]) +result = crew.kickoff(inputs={"youtube_channel_handle": "@exampleDataScienceChannel"}) +``` + +## تفاصيل التنفيذ + +أداة `YoutubeChannelSearchTool` مُنفّذة كفئة فرعية من `RagTool`، التي توفر الوظائف الأساسية للتوليد المعزز بالاسترجاع: + +```python Code +class YoutubeChannelSearchTool(RagTool): + name: str = "Search a Youtube Channels content" + description: str = "A tool that can be used to semantic search a query from a Youtube Channels content." + args_schema: Type[BaseModel] = YoutubeChannelSearchToolSchema + + def __init__(self, youtube_channel_handle: Optional[str] = None, **kwargs): + super().__init__(**kwargs) + if youtube_channel_handle is not None: + kwargs["data_type"] = DataType.YOUTUBE_CHANNEL + self.add(youtube_channel_handle) + self.description = f"A tool that can be used to semantic search a query the {youtube_channel_handle} Youtube Channels content." + self.args_schema = FixedYoutubeChannelSearchToolSchema + self._generate_description() + + def add( + self, + youtube_channel_handle: str, + **kwargs: Any, + ) -> None: + if not youtube_channel_handle.startswith("@"): + youtube_channel_handle = f"@{youtube_channel_handle}" + super().add(youtube_channel_handle, **kwargs) +``` + +## الخلاصة + +توفر أداة `YoutubeChannelSearchTool` طريقة قوية للبحث واستخراج المعلومات من محتوى قنوات YouTube باستخدام تقنيات RAG. من خلال تمكين الوكلاء من البحث عبر فيديوهات قناة كاملة، تسهّل مهام استخراج المعلومات والتحليل التي قد يكون من الصعب تنفيذها بطريقة أخرى. هذه الأداة مفيدة بشكل خاص للبحث وتحليل المحتوى واستخراج المعرفة من قنوات YouTube. \ No newline at end of file diff --git a/docs/ar/tools/search-research/youtubevideosearchtool.mdx b/docs/ar/tools/search-research/youtubevideosearchtool.mdx new file mode 100644 index 000000000..1260ea7e3 --- /dev/null +++ b/docs/ar/tools/search-research/youtubevideosearchtool.mdx @@ -0,0 +1,188 @@ +--- +title: البحث في فيديوهات YouTube باستخدام RAG +description: أداة `YoutubeVideoSearchTool` مصممة لإجراء بحث RAG (التوليد المعزز بالاسترجاع) داخل محتوى فيديو YouTube. +icon: youtube +mode: "wide" +--- + +# `YoutubeVideoSearchTool` + + + لا نزال نعمل على تحسين الأدوات، لذا قد يحدث سلوك غير متوقع أو تغييرات في المستقبل. + + +## الوصف + +هذه الأداة جزء من حزمة `crewai_tools` وهي مصممة لإجراء عمليات بحث دلالية داخل محتوى فيديو YouTube، باستخدام تقنيات التوليد المعزز بالاسترجاع (RAG). +هي واحدة من عدة أدوات "بحث" في الحزمة التي تستفيد من RAG لمصادر مختلفة. +تتيح أداة YoutubeVideoSearchTool المرونة في عمليات البحث؛ يمكن للمستخدمين البحث عبر أي محتوى فيديو YouTube دون تحديد عنوان URL للفيديو، +أو يمكنهم توجيه بحثهم إلى فيديو YouTube محدد من خلال تقديم عنوان URL الخاص به. + +## التثبيت + +لاستخدام `YoutubeVideoSearchTool`، يجب أولاً تثبيت حزمة `crewai_tools`. +تحتوي هذه الحزمة على `YoutubeVideoSearchTool` إلى جانب أدوات مساعدة أخرى مصممة لتعزيز مهام تحليل ومعالجة البيانات. +ثبّت الحزمة بتنفيذ الأمر التالي في الطرفية: + +```shell +pip install 'crewai[tools]' +``` + +## مثال + +يوضح المثال التالي كيفية استخدام `YoutubeVideoSearchTool` مع وكيل CrewAI: + +```python Code +from crewai import Agent, Task, Crew +from crewai_tools import YoutubeVideoSearchTool + +# Initialize the tool for general YouTube video searches +youtube_search_tool = YoutubeVideoSearchTool() + +# Define an agent that uses the tool +video_researcher = Agent( + role="Video Researcher", + goal="Extract relevant information from YouTube videos", + backstory="An expert researcher who specializes in analyzing video content.", + tools=[youtube_search_tool], + verbose=True, +) + +# Example task to search for information in a specific video +research_task = Task( + description="Search for information about machine learning frameworks in the YouTube video at {youtube_video_url}", + expected_output="A summary of the key machine learning frameworks mentioned in the video.", + agent=video_researcher, +) + +# Create and run the crew +crew = Crew(agents=[video_researcher], tasks=[research_task]) +result = crew.kickoff(inputs={"youtube_video_url": "https://youtube.com/watch?v=example"}) +``` + +يمكنك أيضاً تهيئة الأداة بعنوان URL محدد لفيديو YouTube: + +```python Code +# Initialize the tool with a specific YouTube video URL +youtube_search_tool = YoutubeVideoSearchTool( + youtube_video_url='https://youtube.com/watch?v=example' +) + +# Define an agent that uses the tool +video_researcher = Agent( + role="Video Researcher", + goal="Extract relevant information from a specific YouTube video", + backstory="An expert researcher who specializes in analyzing video content.", + tools=[youtube_search_tool], + verbose=True, +) +``` + +## المعاملات + +تقبل أداة `YoutubeVideoSearchTool` المعاملات التالية: + +- **youtube_video_url**: اختياري. عنوان URL لفيديو YouTube للبحث داخله. إذا تم تقديمه أثناء التهيئة، لن يحتاج الوكيل إلى تحديده عند استخدام الأداة. +- **config**: اختياري. تكوين لنظام RAG الأساسي، بما في ذلك إعدادات LLM والتضمينات. +- **summarize**: اختياري. ما إذا كان يجب تلخيص المحتوى المسترجع. الافتراضي هو `False`. + +عند استخدام الأداة مع وكيل، سيحتاج الوكيل إلى تقديم: + +- **search_query**: مطلوب. استعلام البحث للعثور على معلومات ذات صلة في محتوى الفيديو. +- **youtube_video_url**: مطلوب فقط إذا لم يتم تقديمه أثناء التهيئة. عنوان URL لفيديو YouTube للبحث داخله. + +## النموذج المخصص والتضمينات + +بشكل افتراضي، تستخدم الأداة OpenAI لكل من التضمينات والتلخيص. لتخصيص النموذج، يمكنك استخدام قاموس تكوين كما يلي: + +```python Code +youtube_search_tool = YoutubeVideoSearchTool( + config=dict( + llm=dict( + provider="ollama", # or google, openai, anthropic, llama2, ... + config=dict( + model="llama2", + # temperature=0.5, + # top_p=1, + # stream=true, + ), + ), + embedder=dict( + provider="google-generativeai", # or openai, ollama, ... + config=dict( + model_name="gemini-embedding-001", + task_type="RETRIEVAL_DOCUMENT", + # title="Embeddings", + ), + ), + ) +) +``` + +## مثال على التكامل مع الوكيل + +إليك مثالاً أكثر تفصيلاً لكيفية دمج `YoutubeVideoSearchTool` مع وكيل CrewAI: + +```python Code +from crewai import Agent, Task, Crew +from crewai_tools import YoutubeVideoSearchTool + +# Initialize the tool +youtube_search_tool = YoutubeVideoSearchTool() + +# Define an agent that uses the tool +video_researcher = Agent( + role="Video Researcher", + goal="Extract and analyze information from YouTube videos", + backstory="""You are an expert video researcher who specializes in extracting + and analyzing information from YouTube videos. You have a keen eye for detail + and can quickly identify key points and insights from video content.""", + tools=[youtube_search_tool], + verbose=True, +) + +# Create a task for the agent +research_task = Task( + description=""" + Search for information about recent advancements in artificial intelligence + in the YouTube video at {youtube_video_url}. + + Focus on: + 1. Key AI technologies mentioned + 2. Real-world applications discussed + 3. Future predictions made by the speaker + + Provide a comprehensive summary of these points. + """, + expected_output="A detailed summary of AI advancements, applications, and future predictions from the video.", + agent=video_researcher, +) + +# Run the task +crew = Crew(agents=[video_researcher], tasks=[research_task]) +result = crew.kickoff(inputs={"youtube_video_url": "https://youtube.com/watch?v=example"}) +``` + +## تفاصيل التنفيذ + +أداة `YoutubeVideoSearchTool` مُنفّذة كفئة فرعية من `RagTool`، التي توفر الوظائف الأساسية للتوليد المعزز بالاسترجاع: + +```python Code +class YoutubeVideoSearchTool(RagTool): + name: str = "Search a Youtube Video content" + description: str = "A tool that can be used to semantic search a query from a Youtube Video content." + args_schema: Type[BaseModel] = YoutubeVideoSearchToolSchema + + def __init__(self, youtube_video_url: Optional[str] = None, **kwargs): + super().__init__(**kwargs) + if youtube_video_url is not None: + kwargs["data_type"] = DataType.YOUTUBE_VIDEO + self.add(youtube_video_url) + self.description = f"A tool that can be used to semantic search a query the {youtube_video_url} Youtube Video content." + self.args_schema = FixedYoutubeVideoSearchToolSchema + self._generate_description() +``` + +## الخلاصة + +توفر أداة `YoutubeVideoSearchTool` طريقة قوية للبحث واستخراج المعلومات من محتوى فيديو YouTube باستخدام تقنيات RAG. من خلال تمكين الوكلاء من البحث داخل محتوى الفيديو، تسهّل مهام استخراج المعلومات والتحليل التي قد يكون من الصعب تنفيذها بطريقة أخرى. هذه الأداة مفيدة بشكل خاص للبحث وتحليل المحتوى واستخراج المعرفة من مصادر الفيديو. \ No newline at end of file diff --git a/docs/ar/tools/tool-integrations/overview.mdx b/docs/ar/tools/tool-integrations/overview.mdx new file mode 100644 index 000000000..d9d86b6d8 --- /dev/null +++ b/docs/ar/tools/tool-integrations/overview.mdx @@ -0,0 +1,31 @@ +--- +title: نظرة عامة +description: تكاملات لنشر وأتمتة الطواقم مع منصات خارجية +icon: face-smile +mode: "wide" +--- + +## التكاملات المتاحة + + + + استدعاء Amazon Bedrock Agents من CrewAI لتنسيق الإجراءات عبر خدمات AWS. + + + + أتمتة النشر والعمليات من خلال دمج CrewAI مع المنصات وسير العمل الخارجية. + + + +استخدم هذه التكاملات لربط CrewAI بالبنية التحتية وسير العمل الخاصة بك. + diff --git a/docs/ar/tools/web-scraping/brightdata-tools.mdx b/docs/ar/tools/web-scraping/brightdata-tools.mdx new file mode 100644 index 000000000..5809945ea --- /dev/null +++ b/docs/ar/tools/web-scraping/brightdata-tools.mdx @@ -0,0 +1,112 @@ +--- +title: أدوات Bright Data +description: تكاملات Bright Data للبحث في SERP واستخراج البيانات عبر Web Unlocker وDataset API. +icon: spider +mode: "wide" +--- + +# أدوات Bright Data + +هذه المجموعة من الأدوات تدمج خدمات Bright Data لاستخراج البيانات من الويب. + +## التثبيت + +```shell +uv add crewai-tools requests aiohttp +``` + +## متغيرات البيئة + +- `BRIGHT_DATA_API_KEY` (مطلوب) +- `BRIGHT_DATA_ZONE` (لـ SERP/Web Unlocker) + +أنشئ بيانات الاعتماد على https://brightdata.com/ (سجّل، ثم أنشئ رمز API ومنطقة). +راجع التوثيق: https://developers.brightdata.com/ + +## الأدوات المضمنة + +- `BrightDataSearchTool`: بحث SERP (Google/Bing/Yandex) مع خيارات الموقع الجغرافي واللغة والجهاز. +- `BrightDataWebUnlockerTool`: استخراج الصفحات مع تجاوز مكافحة الروبوتات والتصيير. +- `BrightDataDatasetTool`: تشغيل مهام Dataset API وجلب النتائج. + +## أمثلة + +### بحث SERP + +```python Code +from crewai_tools import BrightDataSearchTool + +tool = BrightDataSearchTool( + query="CrewAI", + country="us", +) + +print(tool.run()) +``` + +### Web Unlocker + +```python Code +from crewai_tools import BrightDataWebUnlockerTool + +tool = BrightDataWebUnlockerTool( + url="https://example.com", + format="markdown", +) + +print(tool.run(url="https://example.com")) +``` + +### Dataset API + +```python Code +from crewai_tools import BrightDataDatasetTool + +tool = BrightDataDatasetTool( + dataset_type="ecommerce", + url="https://example.com/product", +) + +print(tool.run()) +``` + +## استكشاف الأخطاء وإصلاحها + +- 401/403: تحقق من `BRIGHT_DATA_API_KEY` و `BRIGHT_DATA_ZONE`. +- محتوى فارغ/محظور: فعّل التصيير أو جرّب منطقة مختلفة. + +## مثال + +```python Code +from crewai import Agent, Task, Crew +from crewai_tools import BrightDataSearchTool + +tool = BrightDataSearchTool( + query="CrewAI", + country="us", +) + +agent = Agent( + role="Web Researcher", + goal="Search with Bright Data", + backstory="Finds reliable results", + tools=[tool], + verbose=True, +) + +task = Task( + description="Search for CrewAI and summarize top results", + expected_output="Short summary with links", + agent=agent, +) + +crew = Crew( + agents=[agent], + tasks=[task], + verbose=True, +) + +result = crew.kickoff() +``` + + diff --git a/docs/ar/tools/web-scraping/browserbaseloadtool.mdx b/docs/ar/tools/web-scraping/browserbaseloadtool.mdx new file mode 100644 index 000000000..0899dbd9f --- /dev/null +++ b/docs/ar/tools/web-scraping/browserbaseloadtool.mdx @@ -0,0 +1,51 @@ +--- +title: أداة تحميل Browserbase +description: Browserbase هي منصة للمطورين لتشغيل وإدارة ومراقبة المتصفحات بدون واجهة بشكل موثوق. +icon: browser +mode: "wide" +--- + +# `BrowserbaseLoadTool` + +## الوصف + +[Browserbase](https://browserbase.com) هي منصة للمطورين لتشغيل وإدارة ومراقبة المتصفحات بدون واجهة بشكل موثوق. + +عزّز عمليات استرجاع بيانات الذكاء الاصطناعي الخاصة بك بـ: + + - [بنية تحتية بدون خادم](https://docs.browserbase.com/under-the-hood) توفر متصفحات موثوقة لاستخراج البيانات من واجهات المستخدم المعقدة + - [وضع التخفي](https://docs.browserbase.com/features/stealth-mode) مع تكتيكات البصمة المضمنة وحل CAPTCHA التلقائي + - [مصحح الجلسات](https://docs.browserbase.com/features/sessions) لفحص جلسة المتصفح مع الجدول الزمني للشبكة والسجلات + - [التصحيح المباشر](https://docs.browserbase.com/guides/session-debug-connection/browser-remote-control) لتصحيح الأتمتة بسرعة + +## التثبيت + +- احصل على مفتاح API ومعرّف المشروع من [browserbase.com](https://browserbase.com) وعيّنهما في متغيرات البيئة (`BROWSERBASE_API_KEY`، `BROWSERBASE_PROJECT_ID`). +- ثبّت [Browserbase SDK](http://github.com/browserbase/python-sdk) مع حزمة `crewai[tools]`: + +```shell +pip install browserbase 'crewai[tools]' +``` + +## مثال + +استخدم BrowserbaseLoadTool كما يلي للسماح لوكيلك بتحميل المواقع: + +```python Code +from crewai_tools import BrowserbaseLoadTool + +# Initialize the tool with the Browserbase API key and Project ID +tool = BrowserbaseLoadTool() +``` + +## المعاملات + +يمكن استخدام المعاملات التالية لتخصيص سلوك `BrowserbaseLoadTool`: + +| المعامل | النوع | الوصف | +|:---------------|:---------|:-------------------------------------------------------------------------------------------------------------------------------------| +| **api_key** | `string` | _اختياري_. مفتاح Browserbase API. الافتراضي هو متغير البيئة `BROWSERBASE_API_KEY`. | +| **project_id** | `string` | _اختياري_. معرّف مشروع Browserbase. الافتراضي هو متغير البيئة `BROWSERBASE_PROJECT_ID`. | +| **text_content** | `bool` | _اختياري_. استرجاع المحتوى النصي فقط. الافتراضي هو `False`. | +| **session_id** | `string` | _اختياري_. تقديم معرّف جلسة موجود. | +| **proxy** | `bool` | _اختياري_. تفعيل/تعطيل البروكسيات. الافتراضي هو `False`. | \ No newline at end of file diff --git a/docs/ar/tools/web-scraping/firecrawlcrawlwebsitetool.mdx b/docs/ar/tools/web-scraping/firecrawlcrawlwebsitetool.mdx new file mode 100644 index 000000000..47c0a2111 --- /dev/null +++ b/docs/ar/tools/web-scraping/firecrawlcrawlwebsitetool.mdx @@ -0,0 +1,48 @@ +--- +title: زحف المواقع باستخدام Firecrawl +description: أداة `FirecrawlCrawlWebsiteTool` مصممة لزحف المواقع وتحويلها إلى markdown نظيف أو بيانات منظمة. +icon: fire-flame +mode: "wide" +--- + +# `FirecrawlCrawlWebsiteTool` + +## الوصف + +[Firecrawl](https://firecrawl.dev) هي منصة لزحف وتحويل أي موقع إلى markdown نظيف أو بيانات منظمة. + +## التثبيت + +- احصل على مفتاح API من [firecrawl.dev](https://firecrawl.dev) وعيّنه في متغيرات البيئة (`FIRECRAWL_API_KEY`). +- ثبّت [Firecrawl SDK](https://github.com/mendableai/firecrawl) مع حزمة `crewai[tools]`: + +```shell +pip install firecrawl-py 'crewai[tools]' +``` + +## مثال + +استخدم FirecrawlScrapeFromWebsiteTool كما يلي للسماح لوكيلك بتحميل المواقع: + +```python Code +from crewai_tools import FirecrawlCrawlWebsiteTool + +tool = FirecrawlCrawlWebsiteTool(url='firecrawl.dev') +``` + +## المعاملات + +- `api_key`: اختياري. يحدد مفتاح Firecrawl API. الافتراضي هو متغير البيئة `FIRECRAWL_API_KEY`. +- `url`: عنوان URL الأساسي لبدء الزحف منه. +- `page_options`: اختياري. + - `onlyMainContent`: اختياري. إرجاع المحتوى الرئيسي فقط للصفحة باستثناء الرؤوس وأشرطة التنقل والتذييلات وغيرها. + - `includeHtml`: اختياري. تضمين محتوى HTML الخام للصفحة. سيُخرج مفتاح html في الاستجابة. +- `crawler_options`: اختياري. خيارات للتحكم في سلوك الزحف. + - `includes`: اختياري. أنماط URL لتضمينها في الزحف. + - `exclude`: اختياري. أنماط URL لاستبعادها من الزحف. + - `generateImgAltText`: اختياري. توليد نص بديل للصور باستخدام LLMs (يتطلب خطة مدفوعة). + - `returnOnlyUrls`: اختياري. إذا كان true، يُرجع عناوين URL فقط كقائمة في حالة الزحف. ملاحظة: ستكون الاستجابة قائمة عناوين URL داخل البيانات، وليست قائمة مستندات. + - `maxDepth`: اختياري. الحد الأقصى لعمق الزحف. العمق 1 هو عنوان URL الأساسي، والعمق 2 يشمل عنوان URL الأساسي وأبنائه المباشرين، وهكذا. + - `mode`: اختياري. وضع الزحف المستخدم. الوضع السريع يزحف أسرع 4 مرات على المواقع بدون خريطة موقع ولكنه قد لا يكون دقيقاً ولا يجب استخدامه على المواقع التي تعتمد بشكل كبير على JavaScript. + - `limit`: اختياري. الحد الأقصى لعدد الصفحات للزحف. + - `timeout`: اختياري. المهلة بالملي ثانية لعملية الزحف. \ No newline at end of file diff --git a/docs/ar/tools/web-scraping/firecrawlscrapewebsitetool.mdx b/docs/ar/tools/web-scraping/firecrawlscrapewebsitetool.mdx new file mode 100644 index 000000000..1bbc4a3b4 --- /dev/null +++ b/docs/ar/tools/web-scraping/firecrawlscrapewebsitetool.mdx @@ -0,0 +1,44 @@ +--- +title: استخراج المواقع باستخدام Firecrawl +description: أداة `FirecrawlScrapeWebsiteTool` مصممة لاستخراج المواقع وتحويلها إلى markdown نظيف أو بيانات منظمة. +icon: fire-flame +mode: "wide" +--- + +# `FirecrawlScrapeWebsiteTool` + +## الوصف + +[Firecrawl](https://firecrawl.dev) هي منصة لزحف وتحويل أي موقع إلى markdown نظيف أو بيانات منظمة. + +## التثبيت + +- احصل على مفتاح API من [firecrawl.dev](https://firecrawl.dev) وعيّنه في متغيرات البيئة (`FIRECRAWL_API_KEY`). +- ثبّت [Firecrawl SDK](https://github.com/mendableai/firecrawl) مع حزمة `crewai[tools]`: + +```shell +pip install firecrawl-py 'crewai[tools]' +``` + +## مثال + +استخدم FirecrawlScrapeWebsiteTool كما يلي للسماح لوكيلك بتحميل المواقع: + +```python Code +from crewai_tools import FirecrawlScrapeWebsiteTool + +tool = FirecrawlScrapeWebsiteTool(url='firecrawl.dev') +``` + +## المعاملات + +- `api_key`: اختياري. يحدد مفتاح Firecrawl API. الافتراضي هو متغير البيئة `FIRECRAWL_API_KEY`. +- `url`: عنوان URL المراد استخراجه. +- `page_options`: اختياري. + - `onlyMainContent`: اختياري. إرجاع المحتوى الرئيسي فقط للصفحة باستثناء الرؤوس وأشرطة التنقل والتذييلات وغيرها. + - `includeHtml`: اختياري. تضمين محتوى HTML الخام للصفحة. سيُخرج مفتاح html في الاستجابة. +- `extractor_options`: اختياري. خيارات لاستخراج المعلومات المنظمة من محتوى الصفحة باستخدام LLM + - `mode`: وضع الاستخراج المستخدم، يدعم حالياً 'llm-extraction' + - `extractionPrompt`: اختياري. موجّه يصف المعلومات المراد استخراجها من الصفحة + - `extractionSchema`: اختياري. المخطط للبيانات المراد استخراجها +- `timeout`: اختياري. المهلة بالملي ثانية للطلب \ No newline at end of file diff --git a/docs/ar/tools/web-scraping/firecrawlsearchtool.mdx b/docs/ar/tools/web-scraping/firecrawlsearchtool.mdx new file mode 100644 index 000000000..7427336f6 --- /dev/null +++ b/docs/ar/tools/web-scraping/firecrawlsearchtool.mdx @@ -0,0 +1,42 @@ +--- +title: بحث Firecrawl +description: أداة `FirecrawlSearchTool` مصممة للبحث في المواقع وتحويلها إلى markdown نظيف أو بيانات منظمة. +icon: fire-flame +mode: "wide" +--- + +# `FirecrawlSearchTool` + +## الوصف + +[Firecrawl](https://firecrawl.dev) هي منصة لزحف وتحويل أي موقع إلى markdown نظيف أو بيانات منظمة. + +## التثبيت + +- احصل على مفتاح API من [firecrawl.dev](https://firecrawl.dev) وعيّنه في متغيرات البيئة (`FIRECRAWL_API_KEY`). +- ثبّت [Firecrawl SDK](https://github.com/mendableai/firecrawl) مع حزمة `crewai[tools]`: + +```shell +pip install firecrawl-py 'crewai[tools]' +``` + +## مثال + +استخدم FirecrawlSearchTool كما يلي للسماح لوكيلك بتحميل المواقع: + +```python Code +from crewai_tools import FirecrawlSearchTool + +tool = FirecrawlSearchTool(query='what is firecrawl?') +``` + +## المعاملات + +- `api_key`: اختياري. يحدد مفتاح Firecrawl API. الافتراضي هو متغير البيئة `FIRECRAWL_API_KEY`. +- `query`: سلسلة استعلام البحث المستخدمة للبحث. +- `page_options`: اختياري. خيارات لتنسيق النتائج. + - `onlyMainContent`: اختياري. إرجاع المحتوى الرئيسي فقط للصفحة باستثناء الرؤوس وأشرطة التنقل والتذييلات وغيرها. + - `includeHtml`: اختياري. تضمين محتوى HTML الخام للصفحة. سيُخرج مفتاح html في الاستجابة. + - `fetchPageContent`: اختياري. جلب المحتوى الكامل للصفحة. +- `search_options`: اختياري. خيارات للتحكم في سلوك الزحف. + - `limit`: اختياري. الحد الأقصى لعدد الصفحات للزحف. \ No newline at end of file diff --git a/docs/ar/tools/web-scraping/hyperbrowserloadtool.mdx b/docs/ar/tools/web-scraping/hyperbrowserloadtool.mdx new file mode 100644 index 000000000..103042379 --- /dev/null +++ b/docs/ar/tools/web-scraping/hyperbrowserloadtool.mdx @@ -0,0 +1,87 @@ +--- +title: أداة تحميل Hyperbrowser +description: أداة `HyperbrowserLoadTool` تتيح استخراج البيانات من الويب والزحف باستخدام Hyperbrowser. +icon: globe +mode: "wide" +--- + +# `HyperbrowserLoadTool` + +## الوصف + +تتيح أداة `HyperbrowserLoadTool` استخراج البيانات من الويب والزحف باستخدام [Hyperbrowser](https://hyperbrowser.ai)، وهي منصة لتشغيل وتوسيع المتصفحات بدون واجهة. تسمح لك هذه الأداة باستخراج صفحة واحدة أو زحف موقع كامل، مع إرجاع المحتوى بتنسيق markdown أو HTML منسّق بشكل صحيح. + +الميزات الرئيسية: +- قابلية توسع فورية - تشغيل مئات جلسات المتصفح في ثوانٍ دون متاعب البنية التحتية +- تكامل بسيط - يعمل بسلاسة مع الأدوات الشائعة مثل Puppeteer و Playwright +- واجهات API قوية - واجهات سهلة الاستخدام لاستخراج/زحف أي موقع +- تجاوز إجراءات مكافحة الروبوتات - وضع التخفي المدمج وحظر الإعلانات وحل CAPTCHA التلقائي والبروكسيات الدوّارة + +## التثبيت + +لاستخدام هذه الأداة، تحتاج إلى تثبيت Hyperbrowser SDK: + +```shell +uv add hyperbrowser +``` + +## خطوات البدء + +لاستخدام `HyperbrowserLoadTool` بفعالية، اتبع هذه الخطوات: + +1. **التسجيل**: توجه إلى [Hyperbrowser](https://app.hyperbrowser.ai/) للتسجيل وتوليد مفتاح API. +2. **مفتاح API**: عيّن متغير البيئة `HYPERBROWSER_API_KEY` أو مرّره مباشرة إلى مُنشئ الأداة. +3. **تثبيت SDK**: ثبّت Hyperbrowser SDK باستخدام الأمر أعلاه. + +## مثال + +يوضح المثال التالي كيفية تهيئة الأداة واستخدامها لاستخراج بيانات من موقع: + +```python Code +from crewai_tools import HyperbrowserLoadTool +from crewai import Agent + +# Initialize the tool with your API key +tool = HyperbrowserLoadTool(api_key="your_api_key") # Or use environment variable + +# Define an agent that uses the tool +@agent +def web_researcher(self) -> Agent: + ''' + This agent uses the HyperbrowserLoadTool to scrape websites + and extract information. + ''' + return Agent( + config=self.agents_config["web_researcher"], + tools=[tool] + ) +``` + +## المعاملات + +تقبل أداة `HyperbrowserLoadTool` المعاملات التالية: + +### معاملات المُنشئ +- **api_key**: اختياري. مفتاح Hyperbrowser API الخاص بك. إذا لم يتم تقديمه، سيتم قراءته من متغير البيئة `HYPERBROWSER_API_KEY`. + +### معاملات التشغيل +- **url**: مطلوب. عنوان URL للموقع المراد استخراجه أو زحفه. +- **operation**: اختياري. العملية المراد تنفيذها على الموقع. إما 'scrape' أو 'crawl'. الافتراضي هو 'scrape'. +- **params**: اختياري. معاملات إضافية لعملية الاستخراج أو الزحف. + +## المعاملات المدعومة + +للحصول على معلومات مفصلة حول جميع المعاملات المدعومة، قم بزيارة: +- [معاملات الاستخراج](https://docs.hyperbrowser.ai/reference/sdks/python/scrape#start-scrape-job-and-wait) +- [معاملات الزحف](https://docs.hyperbrowser.ai/reference/sdks/python/crawl#start-crawl-job-and-wait) + +## تنسيق الإرجاع + +تُرجع الأداة المحتوى بالتنسيق التالي: + +- لعمليات **الاستخراج**: محتوى الصفحة بتنسيق markdown أو HTML. +- لعمليات **الزحف**: محتوى كل صفحة مفصولاً بفواصل، مع تضمين عنوان URL لكل صفحة. + +## الخلاصة + +توفر أداة `HyperbrowserLoadTool` طريقة قوية لاستخراج البيانات من المواقع وزحفها، مع التعامل مع السيناريوهات المعقدة مثل إجراءات مكافحة الروبوتات و CAPTCHA وغيرها. من خلال الاستفادة من منصة Hyperbrowser، تتيح هذه الأداة للوكلاء الوصول إلى محتوى الويب واستخراجه بكفاءة. \ No newline at end of file diff --git a/docs/ar/tools/web-scraping/overview.mdx b/docs/ar/tools/web-scraping/overview.mdx new file mode 100644 index 000000000..3ba3b500e --- /dev/null +++ b/docs/ar/tools/web-scraping/overview.mdx @@ -0,0 +1,112 @@ +--- +title: "نظرة عامة" +description: "استخراج البيانات من المواقع وأتمتة تفاعلات المتصفح باستخدام أدوات استخراج قوية" +icon: "face-smile" +mode: "wide" +--- + +تتيح هذه الأدوات لوكلائك التفاعل مع الويب واستخراج البيانات من المواقع وأتمتة المهام المعتمدة على المتصفح. من الاستخراج البسيط من الويب إلى أتمتة المتصفح المعقدة، تغطي هذه الأدوات جميع احتياجات التفاعل مع الويب. + +## **الأدوات المتاحة** + + + + أداة استخراج بيانات من الويب متعددة الأغراض لاستخراج المحتوى من أي موقع. + + + + استهداف عناصر محددة في صفحات الويب بقدرات استخراج دقيقة. + + + + زحف مواقع كاملة بشكل منهجي باستخدام محرك Firecrawl القوي. + + + + استخراج بيانات عالي الأداء من الويب مع قدرات Firecrawl المتقدمة. + + + + البحث واستخراج محتوى محدد باستخدام ميزات بحث Firecrawl. + + + + أتمتة المتصفح والاستخراج باستخدام قدرات Selenium WebDriver. + + + + استخراج احترافي من الويب مع خدمة ScrapFly المتميزة. + + + + استخراج بيانات من الويب قائم على الرسوم البيانية لعلاقات البيانات المعقدة. + + + + قدرات شاملة للزحف واستخراج البيانات من الويب. + + + + أتمتة المتصفح السحابية مع بنية BrowserBase التحتية. + + + + تفاعلات متصفح سريعة مع محرك HyperBrowser المُحسّن. + + + + أتمتة متصفح ذكية باستخدام أوامر اللغة الطبيعية. + + + + الوصول إلى بيانات الويب على نطاق واسع مع Oxylabs. + + + + تكاملات بحث SERP و Web Unlocker و Dataset API. + + + +## **حالات الاستخدام الشائعة** + +- **استخراج البيانات**: استخراج معلومات المنتجات والأسعار والمراجعات +- **مراقبة المحتوى**: تتبع التغييرات على المواقع ومصادر الأخبار +- **توليد العملاء المحتملين**: استخراج معلومات الاتصال وبيانات الأعمال +- **أبحاث السوق**: جمع المعلومات الاستخباراتية التنافسية وبيانات السوق +- **الاختبار وضمان الجودة**: أتمتة اختبار المتصفح وسير عمل التحقق +- **وسائل التواصل الاجتماعي**: استخراج المنشورات والتعليقات وتحليلات وسائل التواصل الاجتماعي + +## **مثال سريع للبدء** + +```python +from crewai_tools import ScrapeWebsiteTool, FirecrawlScrapeWebsiteTool, SeleniumScrapingTool + +# Create scraping tools +simple_scraper = ScrapeWebsiteTool() +advanced_scraper = FirecrawlScrapeWebsiteTool() +browser_automation = SeleniumScrapingTool() + +# Add to your agent +agent = Agent( + role="Web Research Specialist", + tools=[simple_scraper, advanced_scraper, browser_automation], + goal="Extract and analyze web data efficiently" +) +``` + +## **أفضل ممارسات الاستخراج** + +- **احترام robots.txt**: تحقق دائماً واتبع سياسات استخراج المواقع +- **تحديد المعدل**: نفّذ تأخيرات بين الطلبات لتجنب إرهاق الخوادم +- **وكيل المستخدم**: استخدم سلاسل وكيل مستخدم مناسبة لتعريف الروبوت الخاص بك +- **الامتثال القانوني**: تأكد من أن أنشطة الاستخراج تتوافق مع شروط الخدمة +- **معالجة الأخطاء**: نفّذ معالجة أخطاء قوية لمشاكل الشبكة والطلبات المحظورة +- **جودة البيانات**: تحقق من صحة البيانات المستخرجة ونظّفها قبل المعالجة + +## **دليل اختيار الأداة** + +- **المهام البسيطة**: استخدم `ScrapeWebsiteTool` لاستخراج المحتوى الأساسي +- **المواقع كثيفة JavaScript**: استخدم `SeleniumScrapingTool` للمحتوى الديناميكي +- **التوسع والأداء**: استخدم `FirecrawlScrapeWebsiteTool` للاستخراج بكميات كبيرة +- **البنية التحتية السحابية**: استخدم `BrowserBaseLoadTool` لأتمتة المتصفح القابلة للتوسع +- **سير العمل المعقدة**: استخدم `StagehandTool` لتفاعلات المتصفح الذكية \ No newline at end of file diff --git a/docs/ar/tools/web-scraping/oxylabsscraperstool.mdx b/docs/ar/tools/web-scraping/oxylabsscraperstool.mdx new file mode 100644 index 000000000..b83ba8b33 --- /dev/null +++ b/docs/ar/tools/web-scraping/oxylabsscraperstool.mdx @@ -0,0 +1,237 @@ +--- +title: أدوات استخراج Oxylabs +description: > + تتيح أدوات استخراج Oxylabs الوصول بسهولة إلى المعلومات من المصادر المعنية. يرجى الاطلاع على قائمة المصادر المتاحة أدناه: + - `Amazon Product` + - `Amazon Search` + - `Google Seach` + - `Universal` +icon: globe +mode: "wide" +--- + +## التثبيت + +احصل على بيانات الاعتماد بإنشاء حساب Oxylabs [هنا](https://oxylabs.io). +```shell +pip install 'crewai[tools]' oxylabs +``` +راجع [توثيق Oxylabs](https://developers.oxylabs.io/scraping-solutions/web-scraper-api/targets) للحصول على مزيد من المعلومات حول معاملات API. + +# `OxylabsAmazonProductScraperTool` + +### مثال + +```python +from crewai_tools import OxylabsAmazonProductScraperTool + +# make sure OXYLABS_USERNAME and OXYLABS_PASSWORD variables are set +tool = OxylabsAmazonProductScraperTool() + +result = tool.run(query="AAAAABBBBCC") + +print(result) +``` + +### المعاملات + +- `query` - رمز ASIN المكون من 10 رموز. +- `domain` - توطين النطاق لـ Amazon. +- `geo_location` - موقع _التوصيل إلى_. +- `user_agent_type` - نوع الجهاز والمتصفح. +- `render` - يفعّل تصيير JavaScript عند التعيين إلى `html`. +- `callback_url` - عنوان URL لنقطة نهاية الاستدعاء الخاصة بك. +- `context` - إعدادات وضوابط متقدمة إضافية للمتطلبات المتخصصة. +- `parse` - يُرجع بيانات مُحلّلة عند التعيين إلى true. +- `parsing_instructions` - حدد منطق التحليل وتحويل البيانات الخاص بك الذي سيُنفّذ على نتيجة استخراج HTML. + +### مثال متقدم + +```python +from crewai_tools import OxylabsAmazonProductScraperTool + +# make sure OXYLABS_USERNAME and OXYLABS_PASSWORD variables are set +tool = OxylabsAmazonProductScraperTool( + config={ + "domain": "com", + "parse": True, + "context": [ + { + "key": "autoselect_variant", + "value": True + } + ] + } +) + +result = tool.run(query="AAAAABBBBCC") + +print(result) +``` + +# `OxylabsAmazonSearchScraperTool` + +### مثال + +```python +from crewai_tools import OxylabsAmazonSearchScraperTool + +# make sure OXYLABS_USERNAME and OXYLABS_PASSWORD variables are set +tool = OxylabsAmazonSearchScraperTool() + +result = tool.run(query="headsets") + +print(result) +``` + +### المعاملات + +- `query` - مصطلح بحث Amazon. +- `domain` - توطين النطاق لـ Bestbuy. +- `start_page` - رقم صفحة البداية. +- `pages` - عدد الصفحات المراد استرجاعها. +- `geo_location` - موقع _التوصيل إلى_. +- `user_agent_type` - نوع الجهاز والمتصفح. +- `render` - يفعّل تصيير JavaScript عند التعيين إلى `html`. +- `callback_url` - عنوان URL لنقطة نهاية الاستدعاء الخاصة بك. +- `context` - إعدادات وضوابط متقدمة إضافية للمتطلبات المتخصصة. +- `parse` - يُرجع بيانات مُحلّلة عند التعيين إلى true. +- `parsing_instructions` - حدد منطق التحليل وتحويل البيانات الخاص بك الذي سيُنفّذ على نتيجة استخراج HTML. + +### مثال متقدم + +```python +from crewai_tools import OxylabsAmazonSearchScraperTool + +# make sure OXYLABS_USERNAME and OXYLABS_PASSWORD variables are set +tool = OxylabsAmazonSearchScraperTool( + config={ + "domain": 'nl', + "start_page": 2, + "pages": 2, + "parse": True, + "context": [ + {'key': 'category_id', 'value': 16391693031} + ], + } +) + +result = tool.run(query='nirvana tshirt') + +print(result) +``` + +# `OxylabsGoogleSearchScraperTool` + +### مثال + +```python +from crewai_tools import OxylabsGoogleSearchScraperTool + +# make sure OXYLABS_USERNAME and OXYLABS_PASSWORD variables are set +tool = OxylabsGoogleSearchScraperTool() + +result = tool.run(query="iPhone 16") + +print(result) +``` + +### المعاملات + +- `query` - كلمة البحث المفتاحية. +- `domain` - توطين النطاق لـ Google. +- `start_page` - رقم صفحة البداية. +- `pages` - عدد الصفحات المراد استرجاعها. +- `limit` - عدد النتائج المراد استرجاعها في كل صفحة. +- `locale` - قيمة رأس `Accept-Language` التي تغيّر لغة واجهة صفحة بحث Google. +- `geo_location` - الموقع الجغرافي الذي يجب تكييف النتيجة له. استخدام هذا المعامل بشكل صحيح مهم للغاية للحصول على البيانات الصحيحة. +- `user_agent_type` - نوع الجهاز والمتصفح. +- `render` - يفعّل تصيير JavaScript عند التعيين إلى `html`. +- `callback_url` - عنوان URL لنقطة نهاية الاستدعاء الخاصة بك. +- `context` - إعدادات وضوابط متقدمة إضافية للمتطلبات المتخصصة. +- `parse` - يُرجع بيانات مُحلّلة عند التعيين إلى true. +- `parsing_instructions` - حدد منطق التحليل وتحويل البيانات الخاص بك الذي سيُنفّذ على نتيجة استخراج HTML. + +### مثال متقدم + +```python +from crewai_tools import OxylabsGoogleSearchScraperTool + +# make sure OXYLABS_USERNAME and OXYLABS_PASSWORD variables are set +tool = OxylabsGoogleSearchScraperTool( + config={ + "parse": True, + "geo_location": "Paris, France", + "user_agent_type": "tablet", + } +) + +result = tool.run(query="iPhone 16") + +print(result) +``` + +# `OxylabsUniversalScraperTool` + +### مثال + +```python +from crewai_tools import OxylabsUniversalScraperTool + +# make sure OXYLABS_USERNAME and OXYLABS_PASSWORD variables are set +tool = OxylabsUniversalScraperTool() + +result = tool.run(url="https://ip.oxylabs.io") + +print(result) +``` + +### المعاملات + +- `url` - عنوان URL للموقع المراد استخراجه. +- `user_agent_type` - نوع الجهاز والمتصفح. +- `geo_location` - يعيّن الموقع الجغرافي للبروكسي لاسترجاع البيانات. +- `render` - يفعّل تصيير JavaScript عند التعيين إلى `html`. +- `callback_url` - عنوان URL لنقطة نهاية الاستدعاء الخاصة بك. +- `context` - إعدادات وضوابط متقدمة إضافية للمتطلبات المتخصصة. +- `parse` - يُرجع بيانات مُحلّلة عند التعيين إلى `true`، طالما يوجد مُحلّل مخصص لنوع صفحة عنوان URL المقدم. +- `parsing_instructions` - حدد منطق التحليل وتحويل البيانات الخاص بك الذي سيُنفّذ على نتيجة استخراج HTML. + + +### مثال متقدم + +```python +from crewai_tools import OxylabsUniversalScraperTool + +# make sure OXYLABS_USERNAME and OXYLABS_PASSWORD variables are set +tool = OxylabsUniversalScraperTool( + config={ + "render": "html", + "user_agent_type": "mobile", + "context": [ + {"key": "force_headers", "value": True}, + {"key": "force_cookies", "value": True}, + { + "key": "headers", + "value": { + "Custom-Header-Name": "custom header content", + }, + }, + { + "key": "cookies", + "value": [ + {"key": "NID", "value": "1234567890"}, + {"key": "1P JAR", "value": "0987654321"}, + ], + }, + {"key": "http_method", "value": "get"}, + {"key": "follow_redirects", "value": True}, + {"key": "successful_status_codes", "value": [808, 909]}, + ], + } +) + +result = tool.run(url="https://ip.oxylabs.io") + +print(result) +``` \ No newline at end of file diff --git a/docs/ar/tools/web-scraping/scrapeelementfromwebsitetool.mdx b/docs/ar/tools/web-scraping/scrapeelementfromwebsitetool.mdx new file mode 100644 index 000000000..f84ed8a7d --- /dev/null +++ b/docs/ar/tools/web-scraping/scrapeelementfromwebsitetool.mdx @@ -0,0 +1,140 @@ +--- +title: أداة استخراج عنصر من موقع +description: أداة `ScrapeElementFromWebsiteTool` تتيح لوكلاء CrewAI استخراج عناصر محددة من المواقع باستخدام محددات CSS. +icon: code +mode: "wide" +--- + +# `ScrapeElementFromWebsiteTool` + +## الوصف + +أداة `ScrapeElementFromWebsiteTool` مصممة لاستخراج عناصر محددة من المواقع باستخدام محددات CSS. تسمح هذه الأداة لوكلاء CrewAI باستخراج محتوى مستهدف من صفحات الويب، مما يجعلها مفيدة لمهام استخراج البيانات حيث تكون أجزاء محددة فقط من صفحة الويب مطلوبة. + +## التثبيت + +لاستخدام هذه الأداة، تحتاج إلى تثبيت التبعيات المطلوبة: + +```shell +uv add requests beautifulsoup4 +``` + +## خطوات البدء + +لاستخدام `ScrapeElementFromWebsiteTool` بفعالية، اتبع هذه الخطوات: + +1. **تثبيت التبعيات**: ثبّت الحزم المطلوبة باستخدام الأمر أعلاه. +2. **تحديد محددات CSS**: حدد محددات CSS للعناصر التي تريد استخراجها من الموقع. +3. **تهيئة الأداة**: أنشئ نسخة من الأداة بالمعاملات اللازمة. + +## مثال + +يوضح المثال التالي كيفية استخدام `ScrapeElementFromWebsiteTool` لاستخراج عناصر محددة من موقع: + +```python Code +from crewai import Agent, Task, Crew +from crewai_tools import ScrapeElementFromWebsiteTool + +# Initialize the tool +scrape_tool = ScrapeElementFromWebsiteTool() + +# Define an agent that uses the tool +web_scraper_agent = Agent( + role="Web Scraper", + goal="Extract specific information from websites", + backstory="An expert in web scraping who can extract targeted content from web pages.", + tools=[scrape_tool], + verbose=True, +) + +# Example task to extract headlines from a news website +scrape_task = Task( + description="Extract the main headlines from the CNN homepage. Use the CSS selector '.headline' to target the headline elements.", + expected_output="A list of the main headlines from CNN.", + agent=web_scraper_agent, +) + +# Create and run the crew +crew = Crew(agents=[web_scraper_agent], tasks=[scrape_task]) +result = crew.kickoff() +``` + +يمكنك أيضاً تهيئة الأداة بمعاملات محددة مسبقاً: + +```python Code +# Initialize the tool with predefined parameters +scrape_tool = ScrapeElementFromWebsiteTool( + website_url="https://www.example.com", + css_element=".main-content" +) +``` + +## المعاملات + +تقبل أداة `ScrapeElementFromWebsiteTool` المعاملات التالية أثناء التهيئة: + +- **website_url**: اختياري. عنوان URL للموقع المراد استخراجه. إذا تم تقديمه أثناء التهيئة، لن يحتاج الوكيل إلى تحديده عند استخدام الأداة. +- **css_element**: اختياري. محدد CSS للعناصر المراد استخراجها. إذا تم تقديمه أثناء التهيئة، لن يحتاج الوكيل إلى تحديده عند استخدام الأداة. +- **cookies**: اختياري. قاموس يحتوي على ملفات تعريف الارتباط لإرسالها مع الطلب. يمكن أن يكون مفيداً للمواقع التي تتطلب مصادقة. + +## الاستخدام + +عند استخدام `ScrapeElementFromWebsiteTool` مع وكيل، سيحتاج الوكيل إلى تقديم المعاملات التالية (ما لم يتم تحديدها أثناء التهيئة): + +- **website_url**: عنوان URL للموقع المراد استخراجه. +- **css_element**: محدد CSS للعناصر المراد استخراجها. + +ستُرجع الأداة المحتوى النصي لجميع العناصر المطابقة لمحدد CSS، مفصولة بأسطر جديدة. + +```python Code +# Example of using the tool with an agent +web_scraper_agent = Agent( + role="Web Scraper", + goal="Extract specific elements from websites", + backstory="An expert in web scraping who can extract targeted content using CSS selectors.", + tools=[scrape_tool], + verbose=True, +) + +# Create a task for the agent to extract specific elements +extract_task = Task( + description=""" + Extract all product titles from the featured products section on example.com. + Use the CSS selector '.product-title' to target the title elements. + """, + expected_output="A list of product titles from the website", + agent=web_scraper_agent, +) + +# Run the task through a crew +crew = Crew(agents=[web_scraper_agent], tasks=[extract_task]) +result = crew.kickoff() +``` + +## تفاصيل التنفيذ + +تستخدم أداة `ScrapeElementFromWebsiteTool` مكتبة `requests` لجلب صفحة الويب و `BeautifulSoup` لتحليل HTML واستخراج العناصر المحددة: + +```python Code +class ScrapeElementFromWebsiteTool(BaseTool): + name: str = "Read a website content" + description: str = "A tool that can be used to read a website content." + + # Implementation details... + + def _run(self, **kwargs: Any) -> Any: + website_url = kwargs.get("website_url", self.website_url) + css_element = kwargs.get("css_element", self.css_element) + page = requests.get( + website_url, + headers=self.headers, + cookies=self.cookies if self.cookies else {}, + ) + parsed = BeautifulSoup(page.content, "html.parser") + elements = parsed.select(css_element) + return "\n".join([element.get_text() for element in elements]) +``` + +## الخلاصة + +توفر أداة `ScrapeElementFromWebsiteTool` طريقة قوية لاستخراج عناصر محددة من المواقع باستخدام محددات CSS. من خلال تمكين الوكلاء من استهداف المحتوى الذي يحتاجونه فقط، تجعل مهام استخراج البيانات من الويب أكثر كفاءة وتركيزاً. هذه الأداة مفيدة بشكل خاص لاستخراج البيانات ومراقبة المحتوى ومهام البحث حيث تحتاج معلومات محددة إلى استخراجها من صفحات الويب. \ No newline at end of file diff --git a/docs/ar/tools/web-scraping/scrapegraphscrapetool.mdx b/docs/ar/tools/web-scraping/scrapegraphscrapetool.mdx new file mode 100644 index 000000000..7e9e4ff08 --- /dev/null +++ b/docs/ar/tools/web-scraping/scrapegraphscrapetool.mdx @@ -0,0 +1,197 @@ +--- +title: أداة استخراج Scrapegraph +description: أداة `ScrapegraphScrapeTool` تستفيد من SmartScraper API من Scrapegraph AI لاستخراج المحتوى من المواقع بذكاء. +icon: chart-area +mode: "wide" +--- + +# `ScrapegraphScrapeTool` + +## الوصف + +أداة `ScrapegraphScrapeTool` مصممة للاستفادة من SmartScraper API من Scrapegraph AI لاستخراج المحتوى من المواقع بذكاء. توفر هذه الأداة قدرات متقدمة لاستخراج البيانات من الويب مع استخراج محتوى مدعوم بالذكاء الاصطناعي، مما يجعلها مثالية لمهام جمع البيانات المستهدفة وتحليل المحتوى. على عكس أدوات الاستخراج التقليدية، يمكنها فهم سياق وبنية صفحات الويب لاستخراج المعلومات الأكثر صلة بناءً على موجّهات اللغة الطبيعية. + +## التثبيت + +لاستخدام هذه الأداة، تحتاج إلى تثبيت عميل Scrapegraph لـ Python: + +```shell +uv add scrapegraph-py +``` + +ستحتاج أيضاً إلى إعداد مفتاح Scrapegraph API كمتغير بيئة: + +```shell +export SCRAPEGRAPH_API_KEY="your_api_key" +``` + +يمكنك الحصول على مفتاح API من [Scrapegraph AI](https://scrapegraphai.com). + +## خطوات البدء + +لاستخدام `ScrapegraphScrapeTool` بفعالية، اتبع هذه الخطوات: + +1. **تثبيت التبعيات**: ثبّت الحزمة المطلوبة باستخدام الأمر أعلاه. +2. **إعداد مفتاح API**: عيّن مفتاح Scrapegraph API كمتغير بيئة أو قدمه أثناء التهيئة. +3. **تهيئة الأداة**: أنشئ نسخة من الأداة بالمعاملات اللازمة. +4. **تحديد موجّهات الاستخراج**: أنشئ موجّهات بلغة طبيعية لتوجيه استخراج محتوى محدد. + +## مثال + +يوضح المثال التالي كيفية استخدام `ScrapegraphScrapeTool` لاستخراج المحتوى من موقع: + +```python Code +from crewai import Agent, Task, Crew +from crewai_tools import ScrapegraphScrapeTool + +# Initialize the tool +scrape_tool = ScrapegraphScrapeTool(api_key="your_api_key") + +# Define an agent that uses the tool +web_scraper_agent = Agent( + role="Web Scraper", + goal="Extract specific information from websites", + backstory="An expert in web scraping who can extract targeted content from web pages.", + tools=[scrape_tool], + verbose=True, +) + +# Example task to extract product information from an e-commerce site +scrape_task = Task( + description="Extract product names, prices, and descriptions from the featured products section of example.com.", + expected_output="A structured list of product information including names, prices, and descriptions.", + agent=web_scraper_agent, +) + +# Create and run the crew +crew = Crew(agents=[web_scraper_agent], tasks=[scrape_task]) +result = crew.kickoff() +``` + +يمكنك أيضاً تهيئة الأداة بمعاملات محددة مسبقاً: + +```python Code +# Initialize the tool with predefined parameters +scrape_tool = ScrapegraphScrapeTool( + website_url="https://www.example.com", + user_prompt="Extract all product prices and descriptions", + api_key="your_api_key" +) +``` + +## المعاملات + +تقبل أداة `ScrapegraphScrapeTool` المعاملات التالية أثناء التهيئة: + +- **api_key**: اختياري. مفتاح Scrapegraph API الخاص بك. إذا لم يتم تقديمه، سيبحث عن متغير البيئة `SCRAPEGRAPH_API_KEY`. +- **website_url**: اختياري. عنوان URL للموقع المراد استخراجه. إذا تم تقديمه أثناء التهيئة، لن يحتاج الوكيل إلى تحديده عند استخدام الأداة. +- **user_prompt**: اختياري. تعليمات مخصصة لاستخراج المحتوى. إذا تم تقديمه أثناء التهيئة، لن يحتاج الوكيل إلى تحديده عند استخدام الأداة. +- **enable_logging**: اختياري. ما إذا كان يجب تفعيل التسجيل لعميل Scrapegraph. الافتراضي هو `False`. + +## الاستخدام + +عند استخدام `ScrapegraphScrapeTool` مع وكيل، سيحتاج الوكيل إلى تقديم المعاملات التالية (ما لم يتم تحديدها أثناء التهيئة): + +- **website_url**: عنوان URL للموقع المراد استخراجه. +- **user_prompt**: اختياري. تعليمات مخصصة لاستخراج المحتوى. الافتراضي هو "Extract the main content of the webpage". + +ستُرجع الأداة المحتوى المستخرج بناءً على الموجّه المقدم. + +```python Code +# Example of using the tool with an agent +web_scraper_agent = Agent( + role="Web Scraper", + goal="Extract specific information from websites", + backstory="An expert in web scraping who can extract targeted content from web pages.", + tools=[scrape_tool], + verbose=True, +) + +# Create a task for the agent to extract specific content +extract_task = Task( + description="Extract the main heading and summary from example.com", + expected_output="The main heading and summary from the website", + agent=web_scraper_agent, +) + +# Run the task +crew = Crew(agents=[web_scraper_agent], tasks=[extract_task]) +result = crew.kickoff() +``` + +## معالجة الأخطاء + +قد تُثير أداة `ScrapegraphScrapeTool` الاستثناءات التالية: + +- **ValueError**: عندما يكون مفتاح API مفقوداً أو تنسيق URL غير صالح. +- **RateLimitError**: عند تجاوز حدود معدل API. +- **RuntimeError**: عند فشل عملية الاستخراج (مشاكل شبكة، أخطاء API). + +يُوصى بتوجيه الوكلاء للتعامل مع الأخطاء المحتملة بسلاسة: + +```python Code +# Create a task that includes error handling instructions +robust_extract_task = Task( + description=""" + Extract the main heading from example.com. + Be aware that you might encounter errors such as: + - Invalid URL format + - Missing API key + - Rate limit exceeded + - Network or API errors + + If you encounter any errors, provide a clear explanation of what went wrong + and suggest possible solutions. + """, + expected_output="Either the extracted heading or a clear error explanation", + agent=web_scraper_agent, +) +``` + +## تحديد المعدل + +لدى Scrapegraph API حدود معدل تختلف حسب خطة اشتراكك. ضع في الاعتبار أفضل الممارسات التالية: + +- نفّذ تأخيرات مناسبة بين الطلبات عند معالجة عناوين URL متعددة. +- تعامل مع أخطاء تحديد المعدل بسلاسة في تطبيقك. +- تحقق من حدود خطة API الخاصة بك على لوحة تحكم Scrapegraph. + +## تفاصيل التنفيذ + +تستخدم أداة `ScrapegraphScrapeTool` عميل Scrapegraph لـ Python للتفاعل مع SmartScraper API: + +```python Code +class ScrapegraphScrapeTool(BaseTool): + """ + A tool that uses Scrapegraph AI to intelligently scrape website content. + """ + + # Implementation details... + + def _run(self, **kwargs: Any) -> Any: + website_url = kwargs.get("website_url", self.website_url) + user_prompt = ( + kwargs.get("user_prompt", self.user_prompt) + or "Extract the main content of the webpage" + ) + + if not website_url: + raise ValueError("website_url is required") + + # Validate URL format + self._validate_url(website_url) + + try: + # Make the SmartScraper request + response = self._client.smartscraper( + website_url=website_url, + user_prompt=user_prompt, + ) + + return response + # Error handling... +``` + +## الخلاصة + +توفر أداة `ScrapegraphScrapeTool` طريقة قوية لاستخراج المحتوى من المواقع باستخدام فهم مدعوم بالذكاء الاصطناعي لبنية صفحات الويب. من خلال تمكين الوكلاء من استهداف معلومات محددة باستخدام موجّهات اللغة الطبيعية، تجعل مهام استخراج البيانات من الويب أكثر كفاءة وتركيزاً. هذه الأداة مفيدة بشكل خاص لاستخراج البيانات ومراقبة المحتوى ومهام البحث حيث تحتاج معلومات محددة إلى استخراجها من صفحات الويب. \ No newline at end of file diff --git a/docs/ar/tools/web-scraping/scrapewebsitetool.mdx b/docs/ar/tools/web-scraping/scrapewebsitetool.mdx new file mode 100644 index 000000000..de8402e4a --- /dev/null +++ b/docs/ar/tools/web-scraping/scrapewebsitetool.mdx @@ -0,0 +1,48 @@ +--- +title: استخراج الموقع +description: أداة `ScrapeWebsiteTool` مصممة لاستخراج وقراءة محتوى موقع محدد. +icon: magnifying-glass-location +mode: "wide" +--- + +# `ScrapeWebsiteTool` + + + لا نزال نعمل على تحسين الأدوات، لذا قد يحدث سلوك غير متوقع أو تغييرات في المستقبل. + + +## الوصف + +أداة مصممة لاستخراج وقراءة محتوى موقع محدد. قادرة على التعامل مع أنواع مختلفة من صفحات الويب عن طريق إجراء طلبات HTTP وتحليل محتوى HTML المستلم. +يمكن أن تكون هذه الأداة مفيدة بشكل خاص لمهام استخراج البيانات من الويب وجمع البيانات أو استخراج معلومات محددة من المواقع. + +## التثبيت + +ثبّت حزمة crewai_tools + +```shell +pip install 'crewai[tools]' +``` + +## مثال + +```python +from crewai_tools import ScrapeWebsiteTool + +# To enable scrapping any website it finds during it's execution +tool = ScrapeWebsiteTool() + +# Initialize the tool with the website URL, +# so the agent can only scrap the content of the specified website +tool = ScrapeWebsiteTool(website_url='https://www.example.com') + +# Extract the text from the site +text = tool.run() +print(text) +``` + +## المعاملات + +| المعامل | النوع | الوصف | +|:---------------|:---------|:-------------------------------------------------------------------------------------------------------------------------------------| +| **website_url** | `string` | **إلزامي** عنوان URL للموقع لقراءة الملف. هذا هو المدخل الأساسي للأداة، يحدد محتوى أي موقع يجب استخراجه وقراءته. | \ No newline at end of file diff --git a/docs/ar/tools/web-scraping/scrapflyscrapetool.mdx b/docs/ar/tools/web-scraping/scrapflyscrapetool.mdx new file mode 100644 index 000000000..1f17ae63e --- /dev/null +++ b/docs/ar/tools/web-scraping/scrapflyscrapetool.mdx @@ -0,0 +1,221 @@ +--- +title: أداة استخراج مواقع Scrapfly +description: أداة `ScrapflyScrapeWebsiteTool` تستفيد من Scrapfly web scraping API لاستخراج المحتوى من المواقع بتنسيقات مختلفة. +icon: spider +mode: "wide" +--- + +# `ScrapflyScrapeWebsiteTool` + +## الوصف + +أداة `ScrapflyScrapeWebsiteTool` مصممة للاستفادة من [Scrapfly](https://scrapfly.io/) web scraping API لاستخراج المحتوى من المواقع. توفر هذه الأداة قدرات متقدمة لاستخراج البيانات من الويب مع دعم المتصفح بدون واجهة والبروكسيات وميزات تجاوز مكافحة الروبوتات. تسمح باستخراج بيانات صفحات الويب بتنسيقات متعددة، بما في ذلك HTML الخام و markdown والنص العادي، مما يجعلها مثالية لمجموعة واسعة من مهام استخراج البيانات من الويب. + +## التثبيت + +لاستخدام هذه الأداة، تحتاج إلى تثبيت Scrapfly SDK: + +```shell +uv add scrapfly-sdk +``` + +ستحتاج أيضاً إلى الحصول على مفتاح Scrapfly API بالتسجيل في [scrapfly.io/register](https://www.scrapfly.io/register/). + +## خطوات البدء + +لاستخدام `ScrapflyScrapeWebsiteTool` بفعالية، اتبع هذه الخطوات: + +1. **تثبيت التبعيات**: ثبّت Scrapfly SDK باستخدام الأمر أعلاه. +2. **الحصول على مفتاح API**: سجّل في Scrapfly للحصول على مفتاح API الخاص بك. +3. **تهيئة الأداة**: أنشئ نسخة من الأداة بمفتاح API الخاص بك. +4. **تكوين معاملات الاستخراج**: خصص معاملات الاستخراج بناءً على احتياجاتك. + +## مثال + +يوضح المثال التالي كيفية استخدام `ScrapflyScrapeWebsiteTool` لاستخراج المحتوى من موقع: + +```python Code +from crewai import Agent, Task, Crew +from crewai_tools import ScrapflyScrapeWebsiteTool + +# Initialize the tool +scrape_tool = ScrapflyScrapeWebsiteTool(api_key="your_scrapfly_api_key") + +# Define an agent that uses the tool +web_scraper_agent = Agent( + role="Web Scraper", + goal="Extract information from websites", + backstory="An expert in web scraping who can extract content from any website.", + tools=[scrape_tool], + verbose=True, +) + +# Example task to extract content from a website +scrape_task = Task( + description="Extract the main content from the product page at https://web-scraping.dev/products and summarize the available products.", + expected_output="A summary of the products available on the website.", + agent=web_scraper_agent, +) + +# Create and run the crew +crew = Crew(agents=[web_scraper_agent], tasks=[scrape_task]) +result = crew.kickoff() +``` + +يمكنك أيضاً تخصيص معاملات الاستخراج: + +```python Code +# Example with custom scraping parameters +web_scraper_agent = Agent( + role="Web Scraper", + goal="Extract information from websites with custom parameters", + backstory="An expert in web scraping who can extract content from any website.", + tools=[scrape_tool], + verbose=True, +) + +# The agent will use the tool with parameters like: +# url="https://web-scraping.dev/products" +# scrape_format="markdown" +# ignore_scrape_failures=True +# scrape_config={ +# "asp": True, # Bypass scraping blocking solutions, like Cloudflare +# "render_js": True, # Enable JavaScript rendering with a cloud headless browser +# "proxy_pool": "public_residential_pool", # Select a proxy pool +# "country": "us", # Select a proxy location +# "auto_scroll": True, # Auto scroll the page +# } + +scrape_task = Task( + description="Extract the main content from the product page at https://web-scraping.dev/products using advanced scraping options including JavaScript rendering and proxy settings.", + expected_output="A detailed summary of the products with all available information.", + agent=web_scraper_agent, +) +``` + +## المعاملات + +تقبل أداة `ScrapflyScrapeWebsiteTool` المعاملات التالية: + +### معاملات التهيئة + +- **api_key**: مطلوب. مفتاح Scrapfly API الخاص بك. + +### معاملات التشغيل + +- **url**: مطلوب. عنوان URL للموقع المراد استخراجه. +- **scrape_format**: اختياري. التنسيق الذي يتم استخراج محتوى صفحة الويب به. الخيارات هي "raw" (HTML) أو "markdown" أو "text". الافتراضي هو "markdown". +- **scrape_config**: اختياري. قاموس يحتوي على خيارات تكوين استخراج Scrapfly إضافية. +- **ignore_scrape_failures**: اختياري. ما إذا كان يجب تجاهل الفشل أثناء الاستخراج. إذا تم التعيين إلى `True`، ستُرجع الأداة `None` بدلاً من إثارة استثناء عند فشل الاستخراج. + +## خيارات تكوين Scrapfly + +يسمح معامل `scrape_config` بتخصيص سلوك الاستخراج بالخيارات التالية: + +- **asp**: تفعيل تجاوز حماية مكافحة الاستخراج. +- **render_js**: تفعيل تصيير JavaScript مع متصفح سحابي بدون واجهة. +- **proxy_pool**: اختيار مجموعة بروكسيات (مثل "public_residential_pool"، "datacenter"). +- **country**: اختيار موقع البروكسي (مثل "us"، "uk"). +- **auto_scroll**: التمرير التلقائي للصفحة لتحميل المحتوى المُحمّل كسولاً. +- **js**: تنفيذ كود JavaScript مخصص بواسطة المتصفح بدون واجهة. + +للحصول على قائمة كاملة بخيارات التكوين، راجع [توثيق Scrapfly API](https://scrapfly.io/docs/scrape-api/getting-started). + +## الاستخدام + +عند استخدام `ScrapflyScrapeWebsiteTool` مع وكيل، سيحتاج الوكيل إلى تقديم عنوان URL للموقع المراد استخراجه ويمكنه اختيارياً تحديد التنسيق وخيارات التكوين الإضافية: + +```python Code +# Example of using the tool with an agent +web_scraper_agent = Agent( + role="Web Scraper", + goal="Extract information from websites", + backstory="An expert in web scraping who can extract content from any website.", + tools=[scrape_tool], + verbose=True, +) + +# Create a task for the agent +scrape_task = Task( + description="Extract the main content from example.com in markdown format.", + expected_output="The main content of example.com in markdown format.", + agent=web_scraper_agent, +) + +# Run the task +crew = Crew(agents=[web_scraper_agent], tasks=[scrape_task]) +result = crew.kickoff() +``` + +للاستخدام المتقدم مع تكوين مخصص: + +```python Code +# Create a task with more specific instructions +advanced_scrape_task = Task( + description=""" + Extract content from example.com with the following requirements: + - Convert the content to plain text format + - Enable JavaScript rendering + - Use a US-based proxy + - Handle any scraping failures gracefully + """, + expected_output="The extracted content from example.com", + agent=web_scraper_agent, +) +``` + +## معالجة الأخطاء + +بشكل افتراضي، ستُثير أداة `ScrapflyScrapeWebsiteTool` استثناء إذا فشل الاستخراج. يمكن توجيه الوكلاء للتعامل مع الفشل بسلاسة عن طريق تحديد معامل `ignore_scrape_failures`: + +```python Code +# Create a task that instructs the agent to handle errors +error_handling_task = Task( + description=""" + Extract content from a potentially problematic website and make sure to handle any + scraping failures gracefully by setting ignore_scrape_failures to True. + """, + expected_output="Either the extracted content or a graceful error message", + agent=web_scraper_agent, +) +``` + +## تفاصيل التنفيذ + +تستخدم أداة `ScrapflyScrapeWebsiteTool` Scrapfly SDK للتفاعل مع Scrapfly API: + +```python Code +class ScrapflyScrapeWebsiteTool(BaseTool): + name: str = "Scrapfly web scraping API tool" + description: str = ( + "Scrape a webpage url using Scrapfly and return its content as markdown or text" + ) + + # Implementation details... + + def _run( + self, + url: str, + scrape_format: str = "markdown", + scrape_config: Optional[Dict[str, Any]] = None, + ignore_scrape_failures: Optional[bool] = None, + ): + from scrapfly import ScrapeApiResponse, ScrapeConfig + + scrape_config = scrape_config if scrape_config is not None else {} + try: + response: ScrapeApiResponse = self.scrapfly.scrape( + ScrapeConfig(url, format=scrape_format, **scrape_config) + ) + return response.scrape_result["content"] + except Exception as e: + if ignore_scrape_failures: + logger.error(f"Error fetching data from {url}, exception: {e}") + return None + else: + raise e +``` + +## الخلاصة + +توفر أداة `ScrapflyScrapeWebsiteTool` طريقة قوية لاستخراج المحتوى من المواقع باستخدام قدرات Scrapfly المتقدمة لاستخراج البيانات من الويب. مع ميزات مثل دعم المتصفح بدون واجهة والبروكسيات وتجاوز مكافحة الروبوتات، يمكنها التعامل مع المواقع المعقدة واستخراج المحتوى بتنسيقات مختلفة. هذه الأداة مفيدة بشكل خاص لاستخراج البيانات ومراقبة المحتوى ومهام البحث حيث يكون استخراج البيانات الموثوق من الويب مطلوباً. \ No newline at end of file diff --git a/docs/ar/tools/web-scraping/seleniumscrapingtool.mdx b/docs/ar/tools/web-scraping/seleniumscrapingtool.mdx new file mode 100644 index 000000000..f9d0148a7 --- /dev/null +++ b/docs/ar/tools/web-scraping/seleniumscrapingtool.mdx @@ -0,0 +1,196 @@ +--- +title: أداة استخراج Selenium +description: أداة `SeleniumScrapingTool` مصممة لاستخراج وقراءة محتوى موقع محدد باستخدام Selenium. +icon: clipboard-user +mode: "wide" +--- + +# `SeleniumScrapingTool` + + + هذه الأداة حالياً قيد التطوير. أثناء تحسين قدراتها، قد يواجه المستخدمون سلوكاً غير متوقع. + ملاحظاتكم لا تقدر بثمن لإجراء التحسينات. + + +## الوصف + +أداة `SeleniumScrapingTool` مصنوعة لمهام استخراج البيانات من الويب عالية الكفاءة. +تسمح بالاستخراج الدقيق للمحتوى من صفحات الويب باستخدام محددات CSS لاستهداف عناصر محددة. +تصميمها يخدم مجموعة واسعة من احتياجات الاستخراج، مع توفير المرونة للعمل مع أي عنوان URL مقدم. + +## التثبيت + +لاستخدام هذه الأداة، تحتاج إلى تثبيت حزمة أدوات CrewAI و Selenium: + +```shell +pip install 'crewai[tools]' +uv add selenium webdriver-manager +``` + +ستحتاج أيضاً إلى تثبيت Chrome على نظامك، حيث تستخدم الأداة Chrome WebDriver لأتمتة المتصفح. + +## مثال + +يوضح المثال التالي كيفية استخدام `SeleniumScrapingTool` مع وكيل CrewAI: + +```python Code +from crewai import Agent, Task, Crew, Process +from crewai_tools import SeleniumScrapingTool + +# Initialize the tool +selenium_tool = SeleniumScrapingTool() + +# Define an agent that uses the tool +web_scraper_agent = Agent( + role="Web Scraper", + goal="Extract information from websites using Selenium", + backstory="An expert web scraper who can extract content from dynamic websites.", + tools=[selenium_tool], + verbose=True, +) + +# Example task to scrape content from a website +scrape_task = Task( + description="Extract the main content from the homepage of example.com. Use the CSS selector 'main' to target the main content area.", + expected_output="The main content from example.com's homepage.", + agent=web_scraper_agent, +) + +# Create and run the crew +crew = Crew( + agents=[web_scraper_agent], + tasks=[scrape_task], + verbose=True, + process=Process.sequential, +) +result = crew.kickoff() +``` + +يمكنك أيضاً تهيئة الأداة بمعاملات محددة مسبقاً: + +```python Code +# Initialize the tool with predefined parameters +selenium_tool = SeleniumScrapingTool( + website_url='https://example.com', + css_element='.main-content', + wait_time=5 +) + +# Define an agent that uses the tool +web_scraper_agent = Agent( + role="Web Scraper", + goal="Extract information from websites using Selenium", + backstory="An expert web scraper who can extract content from dynamic websites.", + tools=[selenium_tool], + verbose=True, +) +``` + +## المعاملات + +تقبل أداة `SeleniumScrapingTool` المعاملات التالية أثناء التهيئة: + +- **website_url**: اختياري. عنوان URL للموقع المراد استخراجه. إذا تم تقديمه أثناء التهيئة، لن يحتاج الوكيل إلى تحديده عند استخدام الأداة. +- **css_element**: اختياري. محدد CSS للعناصر المراد استخراجها. إذا تم تقديمه أثناء التهيئة، لن يحتاج الوكيل إلى تحديده عند استخدام الأداة. +- **cookie**: اختياري. قاموس يحتوي على معلومات ملفات تعريف الارتباط، مفيد لمحاكاة جلسة تسجيل دخول للوصول إلى محتوى مقيد. +- **wait_time**: اختياري. يحدد التأخير (بالثواني) قبل الاستخراج، مما يسمح للموقع وأي محتوى ديناميكي بالتحميل الكامل. الافتراضي هو `3` ثوانٍ. +- **return_html**: اختياري. ما إذا كان يجب إرجاع محتوى HTML بدلاً من النص فقط. الافتراضي هو `False`. + +عند استخدام الأداة مع وكيل، سيحتاج الوكيل إلى تقديم المعاملات التالية (ما لم يتم تحديدها أثناء التهيئة): + +- **website_url**: مطلوب. عنوان URL للموقع المراد استخراجه. +- **css_element**: مطلوب. محدد CSS للعناصر المراد استخراجها. + +## مثال على التكامل مع الوكيل + +إليك مثالاً أكثر تفصيلاً لكيفية دمج `SeleniumScrapingTool` مع وكيل CrewAI: + +```python Code +from crewai import Agent, Task, Crew, Process +from crewai_tools import SeleniumScrapingTool + +# Initialize the tool +selenium_tool = SeleniumScrapingTool() + +# Define an agent that uses the tool +web_scraper_agent = Agent( + role="Web Scraper", + goal="Extract and analyze information from dynamic websites", + backstory="""You are an expert web scraper who specializes in extracting + content from dynamic websites that require browser automation. You have + extensive knowledge of CSS selectors and can identify the right selectors + to target specific content on any website.""", + tools=[selenium_tool], + verbose=True, +) + +# Create a task for the agent +scrape_task = Task( + description=""" + Extract the following information from the news website at {website_url}: + + 1. The headlines of all featured articles (CSS selector: '.headline') + 2. The publication dates of these articles (CSS selector: '.pub-date') + 3. The author names where available (CSS selector: '.author') + + Compile this information into a structured format with each article's details grouped together. + """, + expected_output="A structured list of articles with their headlines, publication dates, and authors.", + agent=web_scraper_agent, +) + +# Run the task +crew = Crew( + agents=[web_scraper_agent], + tasks=[scrape_task], + verbose=True, + process=Process.sequential, +) +result = crew.kickoff(inputs={"website_url": "https://news-example.com"}) +``` + +## تفاصيل التنفيذ + +تستخدم أداة `SeleniumScrapingTool` Selenium WebDriver لأتمتة تفاعلات المتصفح: + +```python Code +class SeleniumScrapingTool(BaseTool): + name: str = "Read a website content" + description: str = "A tool that can be used to read a website content." + args_schema: Type[BaseModel] = SeleniumScrapingToolSchema + + def _run(self, **kwargs: Any) -> Any: + website_url = kwargs.get("website_url", self.website_url) + css_element = kwargs.get("css_element", self.css_element) + return_html = kwargs.get("return_html", self.return_html) + driver = self._create_driver(website_url, self.cookie, self.wait_time) + + content = self._get_content(driver, css_element, return_html) + driver.close() + + return "\n".join(content) +``` + +تنفذ الأداة الخطوات التالية: +1. إنشاء نسخة متصفح Chrome بدون واجهة +2. التنقل إلى عنوان URL المحدد +3. الانتظار للمدة المحددة للسماح بتحميل الصفحة +4. إضافة أي ملفات تعريف ارتباط إذا تم تقديمها +5. استخراج المحتوى بناءً على محدد CSS +6. إرجاع المحتوى المستخرج كنص أو HTML +7. إغلاق نسخة المتصفح + +## التعامل مع المحتوى الديناميكي + +أداة `SeleniumScrapingTool` مفيدة بشكل خاص لاستخراج المواقع ذات المحتوى الديناميكي المُحمّل عبر JavaScript. باستخدام نسخة متصفح حقيقية، يمكنها: + +1. تنفيذ JavaScript على الصفحة +2. انتظار تحميل المحتوى الديناميكي +3. التفاعل مع العناصر عند الحاجة +4. استخراج المحتوى الذي لن يكون متاحاً مع طلبات HTTP البسيطة + +يمكنك ضبط معامل `wait_time` لضمان تحميل جميع المحتوى الديناميكي قبل الاستخراج. + +## الخلاصة + +توفر أداة `SeleniumScrapingTool` طريقة قوية لاستخراج المحتوى من المواقع باستخدام أتمتة المتصفح. من خلال تمكين الوكلاء من التفاعل مع المواقع كما يفعل المستخدم الحقيقي، تسهّل استخراج المحتوى الديناميكي الذي يكون صعباً أو مستحيلاً باستخدام طرق أبسط. هذه الأداة مفيدة بشكل خاص للبحث وجمع البيانات ومهام المراقبة التي تتضمن تطبيقات ويب حديثة ذات محتوى مُصيّر بـ JavaScript. \ No newline at end of file diff --git a/docs/ar/tools/web-scraping/serperscrapewebsitetool.mdx b/docs/ar/tools/web-scraping/serperscrapewebsitetool.mdx new file mode 100644 index 000000000..04dc7ae2a --- /dev/null +++ b/docs/ar/tools/web-scraping/serperscrapewebsitetool.mdx @@ -0,0 +1,101 @@ +--- +title: استخراج المواقع عبر Serper +description: أداة `SerperScrapeWebsiteTool` مصممة لاستخراج المواقع واستخلاص محتوى نظيف وقابل للقراءة باستخدام Serper scraping API. +icon: globe +mode: "wide" +--- + +# `SerperScrapeWebsiteTool` + +## الوصف + +هذه الأداة مصممة لاستخراج محتوى المواقع واستخلاص نص نظيف وقابل للقراءة من أي عنوان URL. تستخدم [serper.dev](https://serper.dev) scraping API لجلب ومعالجة صفحات الويب، مع تضمين اختياري لتنسيق markdown لبنية وقابلية قراءة أفضل. + +## التثبيت + +لاستخدام `SerperScrapeWebsiteTool` بفعالية، اتبع هذه الخطوات: + +1. **تثبيت الحزمة**: تأكد من تثبيت حزمة `crewai[tools]` في بيئة Python الخاصة بك. +2. **الحصول على مفتاح API**: احصل على مفتاح `serper.dev` API بالتسجيل للحصول على حساب في `serper.dev`. +3. **تكوين البيئة**: خزّن مفتاح API الذي حصلت عليه في متغير بيئة باسم `SERPER_API_KEY` لتسهيل استخدامه بواسطة الأداة. + +لدمج هذه الأداة في مشروعك، اتبع تعليمات التثبيت أدناه: + +```shell +pip install 'crewai[tools]' +``` + +## مثال + +يوضح المثال التالي كيفية تهيئة الأداة واستخراج بيانات من موقع: + +```python Code +from crewai_tools import SerperScrapeWebsiteTool + +# Initialize the tool for website scraping capabilities +tool = SerperScrapeWebsiteTool() + +# Scrape a website with markdown formatting +result = tool.run(url="https://example.com", include_markdown=True) +``` + +## المعاملات + +تقبل أداة `SerperScrapeWebsiteTool` المعاملات التالية: + +- **url**: مطلوب. عنوان URL للموقع المراد استخراجه. +- **include_markdown**: اختياري. ما إذا كان يجب تضمين تنسيق markdown في المحتوى المستخرج. الافتراضي هو `True`. + +## مثال مع المعاملات + +إليك مثالاً يوضح كيفية استخدام الأداة مع معاملات مختلفة: + +```python Code +from crewai_tools import SerperScrapeWebsiteTool + +tool = SerperScrapeWebsiteTool() + +# Scrape with markdown formatting (default) +markdown_result = tool.run( + url="https://docs.crewai.com", + include_markdown=True +) + +# Scrape without markdown formatting for plain text +plain_result = tool.run( + url="https://docs.crewai.com", + include_markdown=False +) + +print("Markdown formatted content:") +print(markdown_result) + +print("\nPlain text content:") +print(plain_result) +``` + +## حالات الاستخدام + +أداة `SerperScrapeWebsiteTool` مفيدة بشكل خاص لـ: + +- **تحليل المحتوى**: استخراج وتحليل محتوى المواقع لأغراض البحث +- **جمع البيانات**: جمع معلومات منظمة من صفحات الويب +- **معالجة التوثيق**: تحويل التوثيق المبني على الويب إلى تنسيقات قابلة للقراءة +- **التحليل التنافسي**: استخراج بيانات مواقع المنافسين لأبحاث السوق +- **ترحيل المحتوى**: استخراج المحتوى من المواقع الحالية لأغراض الترحيل + +## معالجة الأخطاء + +تتضمن الأداة معالجة شاملة للأخطاء لـ: + +- **مشاكل الشبكة**: التعامل بسلاسة مع مهلات الاتصال وأخطاء الشبكة +- **أخطاء API**: توفير رسائل خطأ مفصلة للمشاكل المتعلقة بـ API +- **عناوين URL غير صالحة**: التحقق من المشاكل المتعلقة بعناوين URL المشوّهة والإبلاغ عنها +- **المصادقة**: رسائل خطأ واضحة لمفاتيح API المفقودة أو غير الصالحة + +## اعتبارات الأمان + +- خزّن دائماً `SERPER_API_KEY` في متغيرات البيئة، ولا تضعه مباشرة في كودك المصدري +- انتبه لحدود المعدل المفروضة من Serper API +- احترم robots.txt وشروط خدمة المواقع عند استخراج المحتوى +- فكر في تنفيذ تأخيرات بين الطلبات لعمليات الاستخراج واسعة النطاق \ No newline at end of file diff --git a/docs/ar/tools/web-scraping/spidertool.mdx b/docs/ar/tools/web-scraping/spidertool.mdx new file mode 100644 index 000000000..5d98ccd53 --- /dev/null +++ b/docs/ar/tools/web-scraping/spidertool.mdx @@ -0,0 +1,93 @@ +--- +title: أداة استخراج Spider +description: أداة `SpiderTool` مصممة لاستخراج وقراءة محتوى موقع محدد باستخدام Spider. +icon: spider-web +mode: "wide" +--- + +# `SpiderTool` + +## الوصف + +[Spider](https://spider.cloud/?ref=crewai) هي [الأسرع](https://github.com/spider-rs/spider/blob/main/benches/BENCHMARKS.md#benchmark-results) +أداة استخراج وزحف مفتوحة المصدر تُرجع بيانات جاهزة لـ LLM. +تحوّل أي موقع إلى HTML نقي أو markdown أو بيانات وصفية أو نص مع تمكين الزحف بإجراءات مخصصة باستخدام الذكاء الاصطناعي. + +## التثبيت + +لاستخدام `SpiderTool` تحتاج إلى تنزيل [Spider SDK](https://pypi.org/project/spider-client/) +وحزمة `crewai[tools]` SDK أيضاً: + +```shell +pip install spider-client 'crewai[tools]' +``` + +## مثال + +يوضح هذا المثال كيفية استخدام `SpiderTool` لتمكين وكيلك من استخراج المواقع وزحفها. +البيانات المُرجعة من Spider API جاهزة بالفعل لـ LLM، لذا لا حاجة لأي تنظيف. + +```python Code +from crewai_tools import SpiderTool + +def main(): + spider_tool = SpiderTool() + + searcher = Agent( + role="Web Research Expert", + goal="Find related information from specific URL's", + backstory="An expert web researcher that uses the web extremely well", + tools=[spider_tool], + verbose=True, + ) + + return_metadata = Task( + description="Scrape https://spider.cloud with a limit of 1 and enable metadata", + expected_output="Metadata and 10 word summary of spider.cloud", + agent=searcher + ) + + crew = Crew( + agents=[searcher], + tasks=[ + return_metadata, + ], + verbose=2 + ) + + crew.kickoff() + +if __name__ == "__main__": + main() +``` + +## المعاملات +| المعامل | النوع | الوصف | +|:------------------|:---------|:-----------------------------------------------------------------------------------------------------------------------------------------------------| +| **api_key** | `string` | يحدد مفتاح Spider API. إذا لم يتم تحديده، يبحث عن `SPIDER_API_KEY` في متغيرات البيئة. | +| **params** | `object` | معاملات اختيارية للطلب. الافتراضي هو `{"return_format": "markdown"}` لتحسين المحتوى لـ LLMs. | +| **request** | `string` | نوع الطلب المراد تنفيذه (`http`، `chrome`، `smart`). `smart` يستخدم HTTP افتراضياً، مع التبديل إلى تصيير JavaScript عند الحاجة. | +| **limit** | `int` | الحد الأقصى لعدد الصفحات للزحف لكل موقع. عيّن إلى `0` أو اتركه للزحف غير المحدود. | +| **depth** | `int` | الحد الأقصى لعمق الزحف. عيّن إلى `0` بدون حد. | +| **cache** | `bool` | يفعّل التخزين المؤقت لـ HTTP لتسريع التشغيلات المتكررة. الافتراضي هو `true`. | +| **budget** | `object` | يعيّن حدوداً على أساس المسار للصفحات المزحوفة، مثل `{"*":1}` لصفحة الجذر فقط. | +| **locale** | `string` | اللغة المحلية للطلب، مثل `en-US`. | +| **cookies** | `string` | ملفات تعريف ارتباط HTTP للطلب. | +| **stealth** | `bool` | يفعّل وضع التخفي لطلبات Chrome لتجنب الاكتشاف. الافتراضي هو `true`. | +| **headers** | `object` | رؤوس HTTP كخريطة من أزواج مفتاح-قيمة لجميع الطلبات. | +| **metadata** | `bool` | يخزّن البيانات الوصفية حول الصفحات والمحتوى، مما يساعد على التوافق مع الذكاء الاصطناعي. الافتراضي هو `false`. | +| **viewport** | `object` | يعيّن أبعاد نافذة العرض لـ Chrome. الافتراضي هو `800x600`. | +| **encoding** | `string` | يحدد نوع الترميز، مثل `UTF-8`، `SHIFT_JIS`. | +| **subdomains** | `bool` | يتضمن النطاقات الفرعية في الزحف. الافتراضي هو `false`. | +| **user_agent** | `string` | وكيل مستخدم HTTP مخصص. الافتراضي هو وكيل عشوائي. | +| **store_data** | `bool` | يفعّل تخزين البيانات للطلب. يتجاوز `storageless` عند التعيين. الافتراضي هو `false`. | +| **gpt_config** | `object` | يسمح للذكاء الاصطناعي بتوليد إجراءات الزحف، مع خطوات تسلسل اختيارية عبر مصفوفة لـ `"prompt"`. | +| **fingerprint** | `bool` | يفعّل البصمة المتقدمة لـ Chrome. | +| **storageless** | `bool` | يمنع جميع عمليات تخزين البيانات، بما في ذلك تضمينات الذكاء الاصطناعي. الافتراضي هو `false`. | +| **readability** | `bool` | يُعالج المحتوى مسبقاً للقراءة عبر [أداة القراءة من Mozilla](https://github.com/mozilla/readability). يحسّن المحتوى لـ LLMs. | +| **return_format** | `string` | التنسيق لإرجاع البيانات: `markdown`، `raw`، `text`، `html2text`. استخدم `raw` لتنسيق الصفحة الافتراضي. | +| **proxy_enabled** | `bool` | يفعّل بروكسيات عالية الأداء لتجنب الحظر على مستوى الشبكة. | +| **query_selector** | `string` | محدد CSS لاستخراج المحتوى من الترميز. | +| **full_resources** | `bool` | يُنزّل جميع الموارد المرتبطة بالموقع. | +| **request_timeout** | `int` | المهلة بالثواني للطلبات (5-60). الافتراضي هو `30`. | +| **run_in_background** | `bool` | يشغّل الطلب في الخلفية، مفيد لتخزين البيانات وتشغيل زحف لوحة التحكم. لا تأثير إذا تم تعيين `storageless`. | \ No newline at end of file diff --git a/docs/ar/tools/web-scraping/stagehandtool.mdx b/docs/ar/tools/web-scraping/stagehandtool.mdx new file mode 100644 index 000000000..338cc7105 --- /dev/null +++ b/docs/ar/tools/web-scraping/stagehandtool.mdx @@ -0,0 +1,245 @@ +--- +title: أداة Stagehand +description: أداة أتمتة الويب التي تدمج Stagehand مع CrewAI للتفاعل مع المتصفح وأتمتة المهام +icon: hand +mode: "wide" +--- + + +# نظرة عامة + +تدمج أداة `StagehandTool` إطار عمل [Stagehand](https://docs.stagehand.dev/get_started/introduction) مع CrewAI، مما يتيح للوكلاء التفاعل مع المواقع الإلكترونية وأتمتة مهام المتصفح باستخدام تعليمات بلغة طبيعية. + +## نظرة عامة + +Stagehand هو إطار عمل قوي لأتمتة المتصفح تم تطويره بواسطة Browserbase ويتيح لوكلاء الذكاء الاصطناعي: + +- التنقل إلى المواقع الإلكترونية +- النقر على الأزرار والروابط والعناصر الأخرى +- ملء النماذج +- استخراج البيانات من صفحات الويب +- مراقبة العناصر وتحديدها +- تنفيذ سير عمل معقدة + +تغلف أداة StagehandTool حزمة Stagehand Python SDK لتزويد وكلاء CrewAI بإمكانيات التحكم في المتصفح من خلال ثلاثة عمليات أساسية: + +1. **Act**: تنفيذ إجراءات مثل النقر والكتابة والتنقل +2. **Extract**: استخراج بيانات منظمة من صفحات الويب +3. **Observe**: تحديد العناصر وتحليلها في الصفحة + +## المتطلبات الأساسية + +قبل استخدام هذه الأداة، تأكد من توفر ما يلي: + +1. حساب على [Browserbase](https://www.browserbase.com/) مع مفتاح API ومعرف المشروع +2. مفتاح API لنموذج لغوي كبير (OpenAI أو Anthropic Claude) +3. تثبيت حزمة Stagehand Python SDK + +قم بتثبيت التبعية المطلوبة: + +```bash +pip install stagehand-py +``` + +## الاستخدام + +### التنفيذ الأساسي + +يمكن تنفيذ أداة StagehandTool بطريقتين: + +#### 1. استخدام مدير السياق (موصى به) + + يُوصى باستخدام مدير السياق لأنه يضمن التنظيف السليم للموارد حتى في حالة حدوث استثناءات. + + +```python +from crewai import Agent, Task, Crew +from crewai_tools import StagehandTool +from stagehand.schemas import AvailableModel + +# Initialize the tool with your API keys using a context manager +with StagehandTool( + api_key="your-browserbase-api-key", + project_id="your-browserbase-project-id", + model_api_key="your-llm-api-key", # OpenAI or Anthropic API key + model_name=AvailableModel.CLAUDE_3_7_SONNET_LATEST, # Optional: specify which model to use +) as stagehand_tool: + # Create an agent with the tool + researcher = Agent( + role="Web Researcher", + goal="Find and summarize information from websites", + backstory="I'm an expert at finding information online.", + verbose=True, + tools=[stagehand_tool], + ) + + # Create a task that uses the tool + research_task = Task( + description="Go to https://www.example.com and tell me what you see on the homepage.", + agent=researcher, + ) + + # Run the crew + crew = Crew( + agents=[researcher], + tasks=[research_task], + verbose=True, + ) + + result = crew.kickoff() + print(result) +``` + +#### 2. إدارة الموارد يدوياً + +```python +from crewai import Agent, Task, Crew +from crewai_tools import StagehandTool +from stagehand.schemas import AvailableModel + +# Initialize the tool with your API keys +stagehand_tool = StagehandTool( + api_key="your-browserbase-api-key", + project_id="your-browserbase-project-id", + model_api_key="your-llm-api-key", + model_name=AvailableModel.CLAUDE_3_7_SONNET_LATEST, +) + +try: + # Create an agent with the tool + researcher = Agent( + role="Web Researcher", + goal="Find and summarize information from websites", + backstory="I'm an expert at finding information online.", + verbose=True, + tools=[stagehand_tool], + ) + + # Create a task that uses the tool + research_task = Task( + description="Go to https://www.example.com and tell me what you see on the homepage.", + agent=researcher, + ) + + # Run the crew + crew = Crew( + agents=[researcher], + tasks=[research_task], + verbose=True, + ) + + result = crew.kickoff() + print(result) +finally: + # Explicitly clean up resources + stagehand_tool.close() +``` + +## أنواع الأوامر + +تدعم أداة StagehandTool ثلاثة أنواع مختلفة من الأوامر لمهام أتمتة الويب المحددة: + +### 1. أمر Act + +يتيح نوع الأمر `act` (الافتراضي) التفاعل مع صفحات الويب مثل النقر على الأزرار وملء النماذج والتنقل. + +```python +# Perform an action (default behavior) +result = stagehand_tool.run( + instruction="Click the login button", + url="https://example.com", + command_type="act" # Default, so can be omitted +) + +# Fill out a form +result = stagehand_tool.run( + instruction="Fill the contact form with name 'John Doe', email 'john@example.com', and message 'Hello world'", + url="https://example.com/contact" +) +``` + +### 2. أمر Extract + +يسترجع نوع الأمر `extract` بيانات منظمة من صفحات الويب. + +```python +# Extract all product information +result = stagehand_tool.run( + instruction="Extract all product names, prices, and descriptions", + url="https://example.com/products", + command_type="extract" +) + +# Extract specific information with a selector +result = stagehand_tool.run( + instruction="Extract the main article title and content", + url="https://example.com/blog/article", + command_type="extract", + selector=".article-container" # Optional CSS selector +) +``` + +### 3. أمر Observe + +يحدد نوع الأمر `observe` عناصر صفحات الويب ويحللها. + +```python +# Find interactive elements +result = stagehand_tool.run( + instruction="Find all interactive elements in the navigation menu", + url="https://example.com", + command_type="observe" +) + +# Identify form fields +result = stagehand_tool.run( + instruction="Identify all the input fields in the registration form", + url="https://example.com/register", + command_type="observe", + selector="#registration-form" +) +``` + +## خيارات الإعداد + +يمكنك تخصيص سلوك أداة StagehandTool باستخدام المعاملات التالية: + +```python +stagehand_tool = StagehandTool( + api_key="your-browserbase-api-key", + project_id="your-browserbase-project-id", + model_api_key="your-llm-api-key", + model_name=AvailableModel.CLAUDE_3_7_SONNET_LATEST, + dom_settle_timeout_ms=5000, # Wait longer for DOM to settle + headless=True, # Run browser in headless mode + self_heal=True, # Attempt to recover from errors + wait_for_captcha_solves=True, # Wait for CAPTCHA solving + verbose=1, # Control logging verbosity (0-3) +) +``` + +## أفضل الممارسات + +1. **كن محدداً**: قدم تعليمات مفصلة للحصول على نتائج أفضل +2. **اختر نوع الأمر المناسب**: حدد نوع الأمر الصحيح لمهمتك +3. **استخدم المحددات**: استفد من محددات CSS لتحسين الدقة +4. **قسّم المهام المعقدة**: قسّم سير العمل المعقدة إلى عدة استدعاءات للأداة +5. **طبّق معالجة الأخطاء**: أضف معالجة الأخطاء للمشكلات المحتملة + +## استكشاف الأخطاء وإصلاحها + + +المشكلات الشائعة وحلولها: + +- **مشكلات الجلسة**: تحقق من مفاتيح API لكل من Browserbase ومزود النموذج اللغوي +- **العنصر غير موجود**: قم بزيادة قيمة `dom_settle_timeout_ms` للصفحات البطيئة +- **فشل الإجراء**: استخدم `observe` لتحديد العناصر الصحيحة أولاً +- **بيانات غير مكتملة**: حسّن التعليمات أو قدم محددات محددة + + +## موارد إضافية + +للأسئلة حول تكامل CrewAI: +- انضم إلى مجتمع Stagehand على [Slack](https://stagehand.dev/slack) +- افتح مشكلة في [مستودع Stagehand](https://github.com/browserbase/stagehand) +- قم بزيارة [وثائق Stagehand](https://docs.stagehand.dev/) diff --git a/docs/docs.json b/docs/docs.json index fb7c13778..bb9750bd8 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -5667,6 +5667,1898 @@ ] } ] + }, + { + "language": "ar", + "global": { + "anchors": [ + { + "anchor": "الموقع", + "href": "https://crewai.com", + "icon": "globe" + }, + { + "anchor": "المنتدى", + "href": "https://community.crewai.com", + "icon": "discourse" + }, + { + "anchor": "المدوّنة", + "href": "https://blog.crewai.com", + "icon": "newspaper" + }, + { + "anchor": "CrewGPT", + "href": "https://chatgpt.com/g/g-qqTuUWsBY-crewai-assistant", + "icon": "robot" + } + ] + }, + "versions": [ + { + "version": "v1.11.1", + "default": true, + "tabs": [ + { + "tab": "الرئيسية", + "icon": "house", + "groups": [ + { + "group": "مرحباً", + "pages": [ + "ar/index" + ] + } + ] + }, + { + "tab": "التقنية التوثيق", + "icon": "book-open", + "groups": [ + { + "group": "البدء", + "pages": [ + "ar/introduction", + "ar/installation", + "ar/quickstart" + ] + }, + { + "group": "الأدلّة", + "pages": [ + { + "group": "الاستراتيجية", + "icon": "compass", + "pages": [ + "ar/guides/concepts/evaluating-use-cases" + ] + }, + { + "group": "الوكلاء", + "icon": "user", + "pages": [ + "ar/guides/agents/crafting-effective-agents" + ] + }, + { + "group": "الطواقم", + "icon": "users", + "pages": [ + "ar/guides/crews/first-crew" + ] + }, + { + "group": "التدفقات", + "icon": "code-branch", + "pages": [ + "ar/guides/flows/first-flow", + "ar/guides/flows/mastering-flow-state" + ] + }, + { + "group": "الأدوات", + "icon": "wrench", + "pages": [ + "ar/guides/tools/publish-custom-tools" + ] + }, + { + "group": "أدوات البرمجة", + "icon": "terminal", + "pages": [ + "ar/guides/coding-tools/agents-md" + ] + }, + { + "group": "متقدّم", + "icon": "gear", + "pages": [ + "ar/guides/advanced/customizing-prompts", + "ar/guides/advanced/fingerprinting" + ] + }, + { + "group": "الترحيل", + "icon": "shuffle", + "pages": [ + "ar/guides/migration/migrating-from-langgraph" + ] + } + ] + }, + { + "group": "المفاهيم الأساسية", + "pages": [ + "ar/concepts/agents", + "ar/concepts/tasks", + "ar/concepts/crews", + "ar/concepts/flows", + "ar/concepts/production-architecture", + "ar/concepts/knowledge", + "ar/concepts/skills", + "ar/concepts/llms", + "ar/concepts/files", + "ar/concepts/processes", + "ar/concepts/collaboration", + "ar/concepts/training", + "ar/concepts/memory", + "ar/concepts/reasoning", + "ar/concepts/planning", + "ar/concepts/testing", + "ar/concepts/cli", + "ar/concepts/tools", + "ar/concepts/event-listener" + ] + }, + { + "group": "تكامل MCP", + "pages": [ + "ar/mcp/overview", + "ar/mcp/dsl-integration", + "ar/mcp/stdio", + "ar/mcp/sse", + "ar/mcp/streamable-http", + "ar/mcp/multiple-servers", + "ar/mcp/security" + ] + }, + { + "group": "الأدوات", + "pages": [ + "ar/tools/overview", + { + "group": "الملفات والمستندات", + "icon": "folder-open", + "pages": [ + "ar/tools/file-document/overview", + "ar/tools/file-document/filereadtool", + "ar/tools/file-document/filewritetool", + "ar/tools/file-document/pdfsearchtool", + "ar/tools/file-document/docxsearchtool", + "ar/tools/file-document/mdxsearchtool", + "ar/tools/file-document/xmlsearchtool", + "ar/tools/file-document/txtsearchtool", + "ar/tools/file-document/jsonsearchtool", + "ar/tools/file-document/csvsearchtool", + "ar/tools/file-document/directorysearchtool", + "ar/tools/file-document/directoryreadtool", + "ar/tools/file-document/ocrtool", + "ar/tools/file-document/pdf-text-writing-tool" + ] + }, + { + "group": "استخراج بيانات الويب", + "icon": "globe", + "pages": [ + "ar/tools/web-scraping/overview", + "ar/tools/web-scraping/scrapewebsitetool", + "ar/tools/web-scraping/scrapeelementfromwebsitetool", + "ar/tools/web-scraping/scrapflyscrapetool", + "ar/tools/web-scraping/seleniumscrapingtool", + "ar/tools/web-scraping/scrapegraphscrapetool", + "ar/tools/web-scraping/spidertool", + "ar/tools/web-scraping/browserbaseloadtool", + "ar/tools/web-scraping/hyperbrowserloadtool", + "ar/tools/web-scraping/stagehandtool", + "ar/tools/web-scraping/firecrawlcrawlwebsitetool", + "ar/tools/web-scraping/firecrawlscrapewebsitetool", + "ar/tools/web-scraping/oxylabsscraperstool", + "ar/tools/web-scraping/brightdata-tools" + ] + }, + { + "group": "البحث والاستكشاف", + "icon": "magnifying-glass", + "pages": [ + "ar/tools/search-research/overview", + "ar/tools/search-research/serperdevtool", + "ar/tools/search-research/bravesearchtool", + "ar/tools/search-research/exasearchtool", + "ar/tools/search-research/linkupsearchtool", + "ar/tools/search-research/githubsearchtool", + "ar/tools/search-research/websitesearchtool", + "ar/tools/search-research/codedocssearchtool", + "ar/tools/search-research/youtubechannelsearchtool", + "ar/tools/search-research/youtubevideosearchtool", + "ar/tools/search-research/tavilysearchtool", + "ar/tools/search-research/tavilyextractortool", + "ar/tools/search-research/arxivpapertool", + "ar/tools/search-research/serpapi-googlesearchtool", + "ar/tools/search-research/serpapi-googleshoppingtool", + "ar/tools/search-research/databricks-query-tool" + ] + }, + { + "group": "قواعد البيانات", + "icon": "database", + "pages": [ + "ar/tools/database-data/overview", + "ar/tools/database-data/mysqltool", + "ar/tools/database-data/pgsearchtool", + "ar/tools/database-data/snowflakesearchtool", + "ar/tools/database-data/nl2sqltool", + "ar/tools/database-data/qdrantvectorsearchtool", + "ar/tools/database-data/weaviatevectorsearchtool", + "ar/tools/database-data/mongodbvectorsearchtool", + "ar/tools/database-data/singlestoresearchtool" + ] + }, + { + "group": "الذكاء الاصطناعي والتعلّم الآلي", + "icon": "brain", + "pages": [ + "ar/tools/ai-ml/overview", + "ar/tools/ai-ml/dalletool", + "ar/tools/ai-ml/visiontool", + "ar/tools/ai-ml/aimindtool", + "ar/tools/ai-ml/llamaindextool", + "ar/tools/ai-ml/langchaintool", + "ar/tools/ai-ml/ragtool", + "ar/tools/ai-ml/codeinterpretertool" + ] + }, + { + "group": "التخزين السحابي", + "icon": "cloud", + "pages": [ + "ar/tools/cloud-storage/overview", + "ar/tools/cloud-storage/s3readertool", + "ar/tools/cloud-storage/s3writertool", + "ar/tools/cloud-storage/bedrockkbretriever" + ] + }, + { + "group": "Integrations", + "icon": "plug", + "pages": [ + "ar/tools/integration/overview", + "ar/tools/integration/bedrockinvokeagenttool", + "ar/tools/integration/crewaiautomationtool" + ] + }, + { + "group": "الأتمتة", + "icon": "bolt", + "pages": [ + "ar/tools/automation/overview", + "ar/tools/automation/apifyactorstool", + "ar/tools/automation/composiotool", + "ar/tools/automation/multiontool", + "ar/tools/automation/zapieractionstool" + ] + } + ] + }, + { + "group": "Observability", + "pages": [ + "ar/observability/tracing", + "ar/observability/overview", + "ar/observability/arize-phoenix", + "ar/observability/braintrust", + "ar/observability/datadog", + "ar/observability/galileo", + "ar/observability/langdb", + "ar/observability/langfuse", + "ar/observability/langtrace", + "ar/observability/maxim", + "ar/observability/mlflow", + "ar/observability/neatlogs", + "ar/observability/openlit", + "ar/observability/opik", + "ar/observability/patronus-evaluation", + "ar/observability/portkey", + "ar/observability/weave" + ] + }, + { + "group": "التعلّم", + "pages": [ + "ar/learn/overview", + "ar/learn/llm-selection-guide", + "ar/learn/conditional-tasks", + "ar/learn/coding-agents", + "ar/learn/create-custom-tools", + "ar/learn/custom-llm", + "ar/learn/custom-manager-agent", + "ar/learn/customizing-agents", + "ar/learn/dalle-image-generation", + "ar/learn/force-tool-output-as-result", + "ar/learn/hierarchical-process", + "ar/learn/human-input-on-execution", + "ar/learn/human-in-the-loop", + "ar/learn/human-feedback-in-flows", + "ar/learn/kickoff-async", + "ar/learn/kickoff-for-each", + "ar/learn/llm-connections", + "ar/learn/multimodal-agents", + "ar/learn/replay-tasks-from-latest-crew-kickoff", + "ar/learn/sequential-process", + "ar/learn/using-annotations", + "ar/learn/execution-hooks", + "ar/learn/llm-hooks", + "ar/learn/tool-hooks" + ] + }, + { + "group": "Telemetry", + "pages": [ + "ar/telemetry" + ] + } + ] + }, + { + "tab": "المؤسسات", + "icon": "briefcase", + "groups": [ + { + "group": "البدء", + "pages": [ + "ar/enterprise/introduction" + ] + }, + { + "group": "البناء", + "pages": [ + "ar/enterprise/features/automations", + "ar/enterprise/features/crew-studio", + "ar/enterprise/features/marketplace", + "ar/enterprise/features/agent-repositories", + "ar/enterprise/features/tools-and-integrations", + "ar/enterprise/features/pii-trace-redactions" + ] + }, + { + "group": "العمليات", + "pages": [ + "ar/enterprise/features/traces", + "ar/enterprise/features/webhook-streaming", + "ar/enterprise/features/hallucination-guardrail", + "ar/enterprise/features/flow-hitl-management" + ] + }, + { + "group": "الإدارة", + "pages": [ + "ar/enterprise/features/rbac" + ] + }, + { + "group": "التكاملات", + "pages": [ + "ar/enterprise/integrations/asana", + "ar/enterprise/integrations/box", + "ar/enterprise/integrations/clickup", + "ar/enterprise/integrations/github", + "ar/enterprise/integrations/gmail", + "ar/enterprise/integrations/google_calendar", + "ar/enterprise/integrations/google_contacts", + "ar/enterprise/integrations/google_docs", + "ar/enterprise/integrations/google_drive", + "ar/enterprise/integrations/google_sheets", + "ar/enterprise/integrations/google_slides", + "ar/enterprise/integrations/hubspot", + "ar/enterprise/integrations/jira", + "ar/enterprise/integrations/linear", + "ar/enterprise/integrations/microsoft_excel", + "ar/enterprise/integrations/microsoft_onedrive", + "ar/enterprise/integrations/microsoft_outlook", + "ar/enterprise/integrations/microsoft_sharepoint", + "ar/enterprise/integrations/microsoft_teams", + "ar/enterprise/integrations/microsoft_word", + "ar/enterprise/integrations/notion", + "ar/enterprise/integrations/salesforce", + "ar/enterprise/integrations/shopify", + "ar/enterprise/integrations/slack", + "ar/enterprise/integrations/stripe", + "ar/enterprise/integrations/zendesk" + ] + }, + { + "group": "How-To Guides", + "pages": [ + "ar/enterprise/guides/build-crew", + "ar/enterprise/guides/prepare-for-deployment", + "ar/enterprise/guides/deploy-to-amp", + "ar/enterprise/guides/private-package-registry", + "ar/enterprise/guides/kickoff-crew", + "ar/enterprise/guides/update-crew", + "ar/enterprise/guides/enable-crew-studio", + "ar/enterprise/guides/capture_telemetry_logs", + "ar/enterprise/guides/azure-openai-setup", + "ar/enterprise/guides/tool-repository", + "ar/enterprise/guides/custom-mcp-server", + "ar/enterprise/guides/react-component-export", + "ar/enterprise/guides/team-management", + "ar/enterprise/guides/human-in-the-loop", + "ar/enterprise/guides/webhook-automation" + ] + }, + { + "group": "المشغّلات", + "pages": [ + "ar/enterprise/guides/automation-triggers", + "ar/enterprise/guides/gmail-trigger", + "ar/enterprise/guides/google-calendar-trigger", + "ar/enterprise/guides/google-drive-trigger", + "ar/enterprise/guides/outlook-trigger", + "ar/enterprise/guides/onedrive-trigger", + "ar/enterprise/guides/microsoft-teams-trigger", + "ar/enterprise/guides/slack-trigger", + "ar/enterprise/guides/hubspot-trigger", + "ar/enterprise/guides/salesforce-trigger", + "ar/enterprise/guides/zapier-trigger" + ] + }, + { + "group": "موارد التعلّم", + "pages": [ + "ar/enterprise/resources/frequently-asked-questions" + ] + } + ] + }, + { + "tab": "API المرجع", + "icon": "magnifying-glass", + "groups": [ + { + "group": "البدء", + "pages": [ + "ar/api-reference/introduction", + "ar/api-reference/inputs", + "ar/api-reference/kickoff", + "ar/api-reference/resume", + "ar/api-reference/status" + ] + } + ] + }, + { + "tab": "أمثلة", + "icon": "code", + "groups": [ + { + "group": "أمثلة", + "pages": [ + "ar/examples/example", + "ar/examples/cookbooks" + ] + } + ] + }, + { + "tab": "التغييرات السجلات", + "icon": "clock", + "groups": [ + { + "group": "سجل التغييرات", + "pages": [ + "ar/changelog" + ] + } + ] + } + ] + }, + { + "version": "v1.11.0", + "tabs": [ + { + "tab": "الرئيسية", + "icon": "house", + "groups": [ + { + "group": "مرحباً", + "pages": [ + "ar/index" + ] + } + ] + }, + { + "tab": "التقنية التوثيق", + "icon": "book-open", + "groups": [ + { + "group": "البدء", + "pages": [ + "ar/introduction", + "ar/installation", + "ar/quickstart" + ] + }, + { + "group": "الأدلّة", + "pages": [ + { + "group": "الاستراتيجية", + "icon": "compass", + "pages": [ + "ar/guides/concepts/evaluating-use-cases" + ] + }, + { + "group": "الوكلاء", + "icon": "user", + "pages": [ + "ar/guides/agents/crafting-effective-agents" + ] + }, + { + "group": "الطواقم", + "icon": "users", + "pages": [ + "ar/guides/crews/first-crew" + ] + }, + { + "group": "التدفقات", + "icon": "code-branch", + "pages": [ + "ar/guides/flows/first-flow", + "ar/guides/flows/mastering-flow-state" + ] + }, + { + "group": "الأدوات", + "icon": "wrench", + "pages": [ + "ar/guides/tools/publish-custom-tools" + ] + }, + { + "group": "أدوات البرمجة", + "icon": "terminal", + "pages": [ + "ar/guides/coding-tools/agents-md" + ] + }, + { + "group": "متقدّم", + "icon": "gear", + "pages": [ + "ar/guides/advanced/customizing-prompts", + "ar/guides/advanced/fingerprinting" + ] + }, + { + "group": "الترحيل", + "icon": "shuffle", + "pages": [ + "ar/guides/migration/migrating-from-langgraph" + ] + } + ] + }, + { + "group": "المفاهيم الأساسية", + "pages": [ + "ar/concepts/agents", + "ar/concepts/tasks", + "ar/concepts/crews", + "ar/concepts/flows", + "ar/concepts/production-architecture", + "ar/concepts/knowledge", + "ar/concepts/llms", + "ar/concepts/files", + "ar/concepts/processes", + "ar/concepts/collaboration", + "ar/concepts/training", + "ar/concepts/memory", + "ar/concepts/reasoning", + "ar/concepts/planning", + "ar/concepts/testing", + "ar/concepts/cli", + "ar/concepts/tools", + "ar/concepts/event-listener" + ] + }, + { + "group": "تكامل MCP", + "pages": [ + "ar/mcp/overview", + "ar/mcp/dsl-integration", + "ar/mcp/stdio", + "ar/mcp/sse", + "ar/mcp/streamable-http", + "ar/mcp/multiple-servers", + "ar/mcp/security" + ] + }, + { + "group": "الأدوات", + "pages": [ + "ar/tools/overview", + { + "group": "الملفات والمستندات", + "icon": "folder-open", + "pages": [ + "ar/tools/file-document/overview", + "ar/tools/file-document/filereadtool", + "ar/tools/file-document/filewritetool", + "ar/tools/file-document/pdfsearchtool", + "ar/tools/file-document/docxsearchtool", + "ar/tools/file-document/mdxsearchtool", + "ar/tools/file-document/xmlsearchtool", + "ar/tools/file-document/txtsearchtool", + "ar/tools/file-document/jsonsearchtool", + "ar/tools/file-document/csvsearchtool", + "ar/tools/file-document/directorysearchtool", + "ar/tools/file-document/directoryreadtool", + "ar/tools/file-document/ocrtool", + "ar/tools/file-document/pdf-text-writing-tool" + ] + }, + { + "group": "استخراج بيانات الويب", + "icon": "globe", + "pages": [ + "ar/tools/web-scraping/overview", + "ar/tools/web-scraping/scrapewebsitetool", + "ar/tools/web-scraping/scrapeelementfromwebsitetool", + "ar/tools/web-scraping/scrapflyscrapetool", + "ar/tools/web-scraping/seleniumscrapingtool", + "ar/tools/web-scraping/scrapegraphscrapetool", + "ar/tools/web-scraping/spidertool", + "ar/tools/web-scraping/browserbaseloadtool", + "ar/tools/web-scraping/hyperbrowserloadtool", + "ar/tools/web-scraping/stagehandtool", + "ar/tools/web-scraping/firecrawlcrawlwebsitetool", + "ar/tools/web-scraping/firecrawlscrapewebsitetool", + "ar/tools/web-scraping/oxylabsscraperstool", + "ar/tools/web-scraping/brightdata-tools" + ] + }, + { + "group": "البحث والاستكشاف", + "icon": "magnifying-glass", + "pages": [ + "ar/tools/search-research/overview", + "ar/tools/search-research/serperdevtool", + "ar/tools/search-research/bravesearchtool", + "ar/tools/search-research/exasearchtool", + "ar/tools/search-research/linkupsearchtool", + "ar/tools/search-research/githubsearchtool", + "ar/tools/search-research/websitesearchtool", + "ar/tools/search-research/codedocssearchtool", + "ar/tools/search-research/youtubechannelsearchtool", + "ar/tools/search-research/youtubevideosearchtool", + "ar/tools/search-research/tavilysearchtool", + "ar/tools/search-research/tavilyextractortool", + "ar/tools/search-research/arxivpapertool", + "ar/tools/search-research/serpapi-googlesearchtool", + "ar/tools/search-research/serpapi-googleshoppingtool", + "ar/tools/search-research/databricks-query-tool" + ] + }, + { + "group": "قواعد البيانات", + "icon": "database", + "pages": [ + "ar/tools/database-data/overview", + "ar/tools/database-data/mysqltool", + "ar/tools/database-data/pgsearchtool", + "ar/tools/database-data/snowflakesearchtool", + "ar/tools/database-data/nl2sqltool", + "ar/tools/database-data/qdrantvectorsearchtool", + "ar/tools/database-data/weaviatevectorsearchtool", + "ar/tools/database-data/mongodbvectorsearchtool", + "ar/tools/database-data/singlestoresearchtool" + ] + }, + { + "group": "الذكاء الاصطناعي والتعلّم الآلي", + "icon": "brain", + "pages": [ + "ar/tools/ai-ml/overview", + "ar/tools/ai-ml/dalletool", + "ar/tools/ai-ml/visiontool", + "ar/tools/ai-ml/aimindtool", + "ar/tools/ai-ml/llamaindextool", + "ar/tools/ai-ml/langchaintool", + "ar/tools/ai-ml/ragtool", + "ar/tools/ai-ml/codeinterpretertool" + ] + }, + { + "group": "التخزين السحابي", + "icon": "cloud", + "pages": [ + "ar/tools/cloud-storage/overview", + "ar/tools/cloud-storage/s3readertool", + "ar/tools/cloud-storage/s3writertool", + "ar/tools/cloud-storage/bedrockkbretriever" + ] + }, + { + "group": "Integrations", + "icon": "plug", + "pages": [ + "ar/tools/integration/overview", + "ar/tools/integration/bedrockinvokeagenttool", + "ar/tools/integration/crewaiautomationtool" + ] + }, + { + "group": "الأتمتة", + "icon": "bolt", + "pages": [ + "ar/tools/automation/overview", + "ar/tools/automation/apifyactorstool", + "ar/tools/automation/composiotool", + "ar/tools/automation/multiontool", + "ar/tools/automation/zapieractionstool" + ] + } + ] + }, + { + "group": "Observability", + "pages": [ + "ar/observability/tracing", + "ar/observability/overview", + "ar/observability/arize-phoenix", + "ar/observability/braintrust", + "ar/observability/datadog", + "ar/observability/galileo", + "ar/observability/langdb", + "ar/observability/langfuse", + "ar/observability/langtrace", + "ar/observability/maxim", + "ar/observability/mlflow", + "ar/observability/neatlogs", + "ar/observability/openlit", + "ar/observability/opik", + "ar/observability/patronus-evaluation", + "ar/observability/portkey", + "ar/observability/weave" + ] + }, + { + "group": "التعلّم", + "pages": [ + "ar/learn/overview", + "ar/learn/llm-selection-guide", + "ar/learn/conditional-tasks", + "ar/learn/coding-agents", + "ar/learn/create-custom-tools", + "ar/learn/custom-llm", + "ar/learn/custom-manager-agent", + "ar/learn/customizing-agents", + "ar/learn/dalle-image-generation", + "ar/learn/force-tool-output-as-result", + "ar/learn/hierarchical-process", + "ar/learn/human-input-on-execution", + "ar/learn/human-in-the-loop", + "ar/learn/human-feedback-in-flows", + "ar/learn/kickoff-async", + "ar/learn/kickoff-for-each", + "ar/learn/llm-connections", + "ar/learn/multimodal-agents", + "ar/learn/replay-tasks-from-latest-crew-kickoff", + "ar/learn/sequential-process", + "ar/learn/using-annotations", + "ar/learn/execution-hooks", + "ar/learn/llm-hooks", + "ar/learn/tool-hooks" + ] + }, + { + "group": "Telemetry", + "pages": [ + "ar/telemetry" + ] + } + ] + }, + { + "tab": "المؤسسات", + "icon": "briefcase", + "groups": [ + { + "group": "البدء", + "pages": [ + "ar/enterprise/introduction" + ] + }, + { + "group": "البناء", + "pages": [ + "ar/enterprise/features/automations", + "ar/enterprise/features/crew-studio", + "ar/enterprise/features/marketplace", + "ar/enterprise/features/agent-repositories", + "ar/enterprise/features/tools-and-integrations", + "ar/enterprise/features/pii-trace-redactions" + ] + }, + { + "group": "العمليات", + "pages": [ + "ar/enterprise/features/traces", + "ar/enterprise/features/webhook-streaming", + "ar/enterprise/features/hallucination-guardrail", + "ar/enterprise/features/flow-hitl-management" + ] + }, + { + "group": "الإدارة", + "pages": [ + "ar/enterprise/features/rbac" + ] + }, + { + "group": "التكاملات", + "pages": [ + "ar/enterprise/integrations/asana", + "ar/enterprise/integrations/box", + "ar/enterprise/integrations/clickup", + "ar/enterprise/integrations/github", + "ar/enterprise/integrations/gmail", + "ar/enterprise/integrations/google_calendar", + "ar/enterprise/integrations/google_contacts", + "ar/enterprise/integrations/google_docs", + "ar/enterprise/integrations/google_drive", + "ar/enterprise/integrations/google_sheets", + "ar/enterprise/integrations/google_slides", + "ar/enterprise/integrations/hubspot", + "ar/enterprise/integrations/jira", + "ar/enterprise/integrations/linear", + "ar/enterprise/integrations/microsoft_excel", + "ar/enterprise/integrations/microsoft_onedrive", + "ar/enterprise/integrations/microsoft_outlook", + "ar/enterprise/integrations/microsoft_sharepoint", + "ar/enterprise/integrations/microsoft_teams", + "ar/enterprise/integrations/microsoft_word", + "ar/enterprise/integrations/notion", + "ar/enterprise/integrations/salesforce", + "ar/enterprise/integrations/shopify", + "ar/enterprise/integrations/slack", + "ar/enterprise/integrations/stripe", + "ar/enterprise/integrations/zendesk" + ] + }, + { + "group": "How-To Guides", + "pages": [ + "ar/enterprise/guides/build-crew", + "ar/enterprise/guides/prepare-for-deployment", + "ar/enterprise/guides/deploy-to-amp", + "ar/enterprise/guides/private-package-registry", + "ar/enterprise/guides/kickoff-crew", + "ar/enterprise/guides/update-crew", + "ar/enterprise/guides/enable-crew-studio", + "ar/enterprise/guides/capture_telemetry_logs", + "ar/enterprise/guides/azure-openai-setup", + "ar/enterprise/guides/tool-repository", + "ar/enterprise/guides/custom-mcp-server", + "ar/enterprise/guides/react-component-export", + "ar/enterprise/guides/team-management", + "ar/enterprise/guides/human-in-the-loop", + "ar/enterprise/guides/webhook-automation" + ] + }, + { + "group": "المشغّلات", + "pages": [ + "ar/enterprise/guides/automation-triggers", + "ar/enterprise/guides/gmail-trigger", + "ar/enterprise/guides/google-calendar-trigger", + "ar/enterprise/guides/google-drive-trigger", + "ar/enterprise/guides/outlook-trigger", + "ar/enterprise/guides/onedrive-trigger", + "ar/enterprise/guides/microsoft-teams-trigger", + "ar/enterprise/guides/slack-trigger", + "ar/enterprise/guides/hubspot-trigger", + "ar/enterprise/guides/salesforce-trigger", + "ar/enterprise/guides/zapier-trigger" + ] + }, + { + "group": "موارد التعلّم", + "pages": [ + "ar/enterprise/resources/frequently-asked-questions" + ] + } + ] + }, + { + "tab": "API المرجع", + "icon": "magnifying-glass", + "groups": [ + { + "group": "البدء", + "pages": [ + "ar/api-reference/introduction", + "ar/api-reference/inputs", + "ar/api-reference/kickoff", + "ar/api-reference/resume", + "ar/api-reference/status" + ] + } + ] + }, + { + "tab": "أمثلة", + "icon": "code", + "groups": [ + { + "group": "أمثلة", + "pages": [ + "ar/examples/example", + "ar/examples/cookbooks" + ] + } + ] + }, + { + "tab": "التغييرات السجلات", + "icon": "clock", + "groups": [ + { + "group": "سجل التغييرات", + "pages": [ + "ar/changelog" + ] + } + ] + } + ] + }, + { + "version": "v1.10.1", + "tabs": [ + { + "tab": "الرئيسية", + "icon": "house", + "groups": [ + { + "group": "مرحباً", + "pages": [ + "ar/index" + ] + } + ] + }, + { + "tab": "التقنية التوثيق", + "icon": "book-open", + "groups": [ + { + "group": "البدء", + "pages": [ + "ar/introduction", + "ar/installation", + "ar/quickstart" + ] + }, + { + "group": "الأدلّة", + "pages": [ + { + "group": "الاستراتيجية", + "icon": "compass", + "pages": [ + "ar/guides/concepts/evaluating-use-cases" + ] + }, + { + "group": "الوكلاء", + "icon": "user", + "pages": [ + "ar/guides/agents/crafting-effective-agents" + ] + }, + { + "group": "الطواقم", + "icon": "users", + "pages": [ + "ar/guides/crews/first-crew" + ] + }, + { + "group": "التدفقات", + "icon": "code-branch", + "pages": [ + "ar/guides/flows/first-flow", + "ar/guides/flows/mastering-flow-state" + ] + }, + { + "group": "الأدوات", + "icon": "wrench", + "pages": [ + "ar/guides/tools/publish-custom-tools" + ] + }, + { + "group": "أدوات البرمجة", + "icon": "terminal", + "pages": [ + "ar/guides/coding-tools/agents-md" + ] + }, + { + "group": "متقدّم", + "icon": "gear", + "pages": [ + "ar/guides/advanced/customizing-prompts", + "ar/guides/advanced/fingerprinting" + ] + }, + { + "group": "الترحيل", + "icon": "shuffle", + "pages": [ + "ar/guides/migration/migrating-from-langgraph" + ] + } + ] + }, + { + "group": "المفاهيم الأساسية", + "pages": [ + "ar/concepts/agents", + "ar/concepts/tasks", + "ar/concepts/crews", + "ar/concepts/flows", + "ar/concepts/production-architecture", + "ar/concepts/knowledge", + "ar/concepts/llms", + "ar/concepts/files", + "ar/concepts/processes", + "ar/concepts/collaboration", + "ar/concepts/training", + "ar/concepts/memory", + "ar/concepts/reasoning", + "ar/concepts/planning", + "ar/concepts/testing", + "ar/concepts/cli", + "ar/concepts/tools", + "ar/concepts/event-listener" + ] + }, + { + "group": "تكامل MCP", + "pages": [ + "ar/mcp/overview", + "ar/mcp/dsl-integration", + "ar/mcp/stdio", + "ar/mcp/sse", + "ar/mcp/streamable-http", + "ar/mcp/multiple-servers", + "ar/mcp/security" + ] + }, + { + "group": "الأدوات", + "pages": [ + "ar/tools/overview", + { + "group": "الملفات والمستندات", + "icon": "folder-open", + "pages": [ + "ar/tools/file-document/overview", + "ar/tools/file-document/filereadtool", + "ar/tools/file-document/filewritetool", + "ar/tools/file-document/pdfsearchtool", + "ar/tools/file-document/docxsearchtool", + "ar/tools/file-document/mdxsearchtool", + "ar/tools/file-document/xmlsearchtool", + "ar/tools/file-document/txtsearchtool", + "ar/tools/file-document/jsonsearchtool", + "ar/tools/file-document/csvsearchtool", + "ar/tools/file-document/directorysearchtool", + "ar/tools/file-document/directoryreadtool", + "ar/tools/file-document/ocrtool", + "ar/tools/file-document/pdf-text-writing-tool" + ] + }, + { + "group": "استخراج بيانات الويب", + "icon": "globe", + "pages": [ + "ar/tools/web-scraping/overview", + "ar/tools/web-scraping/scrapewebsitetool", + "ar/tools/web-scraping/scrapeelementfromwebsitetool", + "ar/tools/web-scraping/scrapflyscrapetool", + "ar/tools/web-scraping/seleniumscrapingtool", + "ar/tools/web-scraping/scrapegraphscrapetool", + "ar/tools/web-scraping/spidertool", + "ar/tools/web-scraping/browserbaseloadtool", + "ar/tools/web-scraping/hyperbrowserloadtool", + "ar/tools/web-scraping/stagehandtool", + "ar/tools/web-scraping/firecrawlcrawlwebsitetool", + "ar/tools/web-scraping/firecrawlscrapewebsitetool", + "ar/tools/web-scraping/oxylabsscraperstool", + "ar/tools/web-scraping/brightdata-tools" + ] + }, + { + "group": "البحث والاستكشاف", + "icon": "magnifying-glass", + "pages": [ + "ar/tools/search-research/overview", + "ar/tools/search-research/serperdevtool", + "ar/tools/search-research/bravesearchtool", + "ar/tools/search-research/exasearchtool", + "ar/tools/search-research/linkupsearchtool", + "ar/tools/search-research/githubsearchtool", + "ar/tools/search-research/websitesearchtool", + "ar/tools/search-research/codedocssearchtool", + "ar/tools/search-research/youtubechannelsearchtool", + "ar/tools/search-research/youtubevideosearchtool", + "ar/tools/search-research/tavilysearchtool", + "ar/tools/search-research/tavilyextractortool", + "ar/tools/search-research/arxivpapertool", + "ar/tools/search-research/serpapi-googlesearchtool", + "ar/tools/search-research/serpapi-googleshoppingtool", + "ar/tools/search-research/databricks-query-tool" + ] + }, + { + "group": "قواعد البيانات", + "icon": "database", + "pages": [ + "ar/tools/database-data/overview", + "ar/tools/database-data/mysqltool", + "ar/tools/database-data/pgsearchtool", + "ar/tools/database-data/snowflakesearchtool", + "ar/tools/database-data/nl2sqltool", + "ar/tools/database-data/qdrantvectorsearchtool", + "ar/tools/database-data/weaviatevectorsearchtool", + "ar/tools/database-data/mongodbvectorsearchtool", + "ar/tools/database-data/singlestoresearchtool" + ] + }, + { + "group": "الذكاء الاصطناعي والتعلّم الآلي", + "icon": "brain", + "pages": [ + "ar/tools/ai-ml/overview", + "ar/tools/ai-ml/dalletool", + "ar/tools/ai-ml/visiontool", + "ar/tools/ai-ml/aimindtool", + "ar/tools/ai-ml/llamaindextool", + "ar/tools/ai-ml/langchaintool", + "ar/tools/ai-ml/ragtool", + "ar/tools/ai-ml/codeinterpretertool" + ] + }, + { + "group": "التخزين السحابي", + "icon": "cloud", + "pages": [ + "ar/tools/cloud-storage/overview", + "ar/tools/cloud-storage/s3readertool", + "ar/tools/cloud-storage/s3writertool", + "ar/tools/cloud-storage/bedrockkbretriever" + ] + }, + { + "group": "Integrations", + "icon": "plug", + "pages": [ + "ar/tools/integration/overview", + "ar/tools/integration/bedrockinvokeagenttool", + "ar/tools/integration/crewaiautomationtool" + ] + }, + { + "group": "الأتمتة", + "icon": "bolt", + "pages": [ + "ar/tools/automation/overview", + "ar/tools/automation/apifyactorstool", + "ar/tools/automation/composiotool", + "ar/tools/automation/multiontool", + "ar/tools/automation/zapieractionstool" + ] + } + ] + }, + { + "group": "Observability", + "pages": [ + "ar/observability/tracing", + "ar/observability/overview", + "ar/observability/arize-phoenix", + "ar/observability/braintrust", + "ar/observability/datadog", + "ar/observability/galileo", + "ar/observability/langdb", + "ar/observability/langfuse", + "ar/observability/langtrace", + "ar/observability/maxim", + "ar/observability/mlflow", + "ar/observability/neatlogs", + "ar/observability/openlit", + "ar/observability/opik", + "ar/observability/patronus-evaluation", + "ar/observability/portkey", + "ar/observability/weave" + ] + }, + { + "group": "التعلّم", + "pages": [ + "ar/learn/overview", + "ar/learn/llm-selection-guide", + "ar/learn/conditional-tasks", + "ar/learn/coding-agents", + "ar/learn/create-custom-tools", + "ar/learn/custom-llm", + "ar/learn/custom-manager-agent", + "ar/learn/customizing-agents", + "ar/learn/dalle-image-generation", + "ar/learn/force-tool-output-as-result", + "ar/learn/hierarchical-process", + "ar/learn/human-input-on-execution", + "ar/learn/human-in-the-loop", + "ar/learn/human-feedback-in-flows", + "ar/learn/kickoff-async", + "ar/learn/kickoff-for-each", + "ar/learn/llm-connections", + "ar/learn/multimodal-agents", + "ar/learn/replay-tasks-from-latest-crew-kickoff", + "ar/learn/sequential-process", + "ar/learn/using-annotations", + "ar/learn/execution-hooks", + "ar/learn/llm-hooks", + "ar/learn/tool-hooks" + ] + }, + { + "group": "Telemetry", + "pages": [ + "ar/telemetry" + ] + } + ] + }, + { + "tab": "المؤسسات", + "icon": "briefcase", + "groups": [ + { + "group": "البدء", + "pages": [ + "ar/enterprise/introduction" + ] + }, + { + "group": "البناء", + "pages": [ + "ar/enterprise/features/automations", + "ar/enterprise/features/crew-studio", + "ar/enterprise/features/marketplace", + "ar/enterprise/features/agent-repositories", + "ar/enterprise/features/tools-and-integrations", + "ar/enterprise/features/pii-trace-redactions" + ] + }, + { + "group": "العمليات", + "pages": [ + "ar/enterprise/features/traces", + "ar/enterprise/features/webhook-streaming", + "ar/enterprise/features/hallucination-guardrail", + "ar/enterprise/features/flow-hitl-management" + ] + }, + { + "group": "الإدارة", + "pages": [ + "ar/enterprise/features/rbac" + ] + }, + { + "group": "التكاملات", + "pages": [ + "ar/enterprise/integrations/asana", + "ar/enterprise/integrations/box", + "ar/enterprise/integrations/clickup", + "ar/enterprise/integrations/github", + "ar/enterprise/integrations/gmail", + "ar/enterprise/integrations/google_calendar", + "ar/enterprise/integrations/google_contacts", + "ar/enterprise/integrations/google_docs", + "ar/enterprise/integrations/google_drive", + "ar/enterprise/integrations/google_sheets", + "ar/enterprise/integrations/google_slides", + "ar/enterprise/integrations/hubspot", + "ar/enterprise/integrations/jira", + "ar/enterprise/integrations/linear", + "ar/enterprise/integrations/microsoft_excel", + "ar/enterprise/integrations/microsoft_onedrive", + "ar/enterprise/integrations/microsoft_outlook", + "ar/enterprise/integrations/microsoft_sharepoint", + "ar/enterprise/integrations/microsoft_teams", + "ar/enterprise/integrations/microsoft_word", + "ar/enterprise/integrations/notion", + "ar/enterprise/integrations/salesforce", + "ar/enterprise/integrations/shopify", + "ar/enterprise/integrations/slack", + "ar/enterprise/integrations/stripe", + "ar/enterprise/integrations/zendesk" + ] + }, + { + "group": "How-To Guides", + "pages": [ + "ar/enterprise/guides/build-crew", + "ar/enterprise/guides/prepare-for-deployment", + "ar/enterprise/guides/deploy-to-amp", + "ar/enterprise/guides/private-package-registry", + "ar/enterprise/guides/kickoff-crew", + "ar/enterprise/guides/update-crew", + "ar/enterprise/guides/enable-crew-studio", + "ar/enterprise/guides/capture_telemetry_logs", + "ar/enterprise/guides/azure-openai-setup", + "ar/enterprise/guides/tool-repository", + "ar/enterprise/guides/custom-mcp-server", + "ar/enterprise/guides/react-component-export", + "ar/enterprise/guides/team-management", + "ar/enterprise/guides/human-in-the-loop", + "ar/enterprise/guides/webhook-automation" + ] + }, + { + "group": "المشغّلات", + "pages": [ + "ar/enterprise/guides/automation-triggers", + "ar/enterprise/guides/gmail-trigger", + "ar/enterprise/guides/google-calendar-trigger", + "ar/enterprise/guides/google-drive-trigger", + "ar/enterprise/guides/outlook-trigger", + "ar/enterprise/guides/onedrive-trigger", + "ar/enterprise/guides/microsoft-teams-trigger", + "ar/enterprise/guides/slack-trigger", + "ar/enterprise/guides/hubspot-trigger", + "ar/enterprise/guides/salesforce-trigger", + "ar/enterprise/guides/zapier-trigger" + ] + }, + { + "group": "موارد التعلّم", + "pages": [ + "ar/enterprise/resources/frequently-asked-questions" + ] + } + ] + }, + { + "tab": "API المرجع", + "icon": "magnifying-glass", + "groups": [ + { + "group": "البدء", + "pages": [ + "ar/api-reference/introduction", + "ar/api-reference/inputs", + "ar/api-reference/kickoff", + "ar/api-reference/resume", + "ar/api-reference/status" + ] + } + ] + }, + { + "tab": "أمثلة", + "icon": "code", + "groups": [ + { + "group": "أمثلة", + "pages": [ + "ar/examples/example", + "ar/examples/cookbooks" + ] + } + ] + }, + { + "tab": "التغييرات السجلات", + "icon": "clock", + "groups": [ + { + "group": "سجل التغييرات", + "pages": [ + "ar/changelog" + ] + } + ] + } + ] + }, + { + "version": "v1.10.0", + "tabs": [ + { + "tab": "الرئيسية", + "icon": "house", + "groups": [ + { + "group": "مرحباً", + "pages": [ + "ar/index" + ] + } + ] + }, + { + "tab": "التقنية التوثيق", + "icon": "book-open", + "groups": [ + { + "group": "البدء", + "pages": [ + "ar/introduction", + "ar/installation", + "ar/quickstart" + ] + }, + { + "group": "الأدلّة", + "pages": [ + { + "group": "الاستراتيجية", + "icon": "compass", + "pages": [ + "ar/guides/concepts/evaluating-use-cases" + ] + }, + { + "group": "الوكلاء", + "icon": "user", + "pages": [ + "ar/guides/agents/crafting-effective-agents" + ] + }, + { + "group": "الطواقم", + "icon": "users", + "pages": [ + "ar/guides/crews/first-crew" + ] + }, + { + "group": "التدفقات", + "icon": "code-branch", + "pages": [ + "ar/guides/flows/first-flow", + "ar/guides/flows/mastering-flow-state" + ] + }, + { + "group": "الأدوات", + "icon": "wrench", + "pages": [ + "ar/guides/tools/publish-custom-tools" + ] + }, + { + "group": "أدوات البرمجة", + "icon": "terminal", + "pages": [ + "ar/guides/coding-tools/agents-md" + ] + }, + { + "group": "متقدّم", + "icon": "gear", + "pages": [ + "ar/guides/advanced/customizing-prompts", + "ar/guides/advanced/fingerprinting" + ] + }, + { + "group": "الترحيل", + "icon": "shuffle", + "pages": [ + "ar/guides/migration/migrating-from-langgraph" + ] + } + ] + }, + { + "group": "المفاهيم الأساسية", + "pages": [ + "ar/concepts/agents", + "ar/concepts/tasks", + "ar/concepts/crews", + "ar/concepts/flows", + "ar/concepts/production-architecture", + "ar/concepts/knowledge", + "ar/concepts/skills", + "ar/concepts/llms", + "ar/concepts/files", + "ar/concepts/processes", + "ar/concepts/collaboration", + "ar/concepts/training", + "ar/concepts/memory", + "ar/concepts/reasoning", + "ar/concepts/planning", + "ar/concepts/testing", + "ar/concepts/cli", + "ar/concepts/tools", + "ar/concepts/event-listener" + ] + }, + { + "group": "تكامل MCP", + "pages": [ + "ar/mcp/overview", + "ar/mcp/dsl-integration", + "ar/mcp/stdio", + "ar/mcp/sse", + "ar/mcp/streamable-http", + "ar/mcp/multiple-servers", + "ar/mcp/security" + ] + }, + { + "group": "الأدوات", + "pages": [ + "ar/tools/overview", + { + "group": "الملفات والمستندات", + "icon": "folder-open", + "pages": [ + "ar/tools/file-document/overview", + "ar/tools/file-document/filereadtool", + "ar/tools/file-document/filewritetool", + "ar/tools/file-document/pdfsearchtool", + "ar/tools/file-document/docxsearchtool", + "ar/tools/file-document/mdxsearchtool", + "ar/tools/file-document/xmlsearchtool", + "ar/tools/file-document/txtsearchtool", + "ar/tools/file-document/jsonsearchtool", + "ar/tools/file-document/csvsearchtool", + "ar/tools/file-document/directorysearchtool", + "ar/tools/file-document/directoryreadtool", + "ar/tools/file-document/ocrtool", + "ar/tools/file-document/pdf-text-writing-tool" + ] + }, + { + "group": "استخراج بيانات الويب", + "icon": "globe", + "pages": [ + "ar/tools/web-scraping/overview", + "ar/tools/web-scraping/scrapewebsitetool", + "ar/tools/web-scraping/scrapeelementfromwebsitetool", + "ar/tools/web-scraping/scrapflyscrapetool", + "ar/tools/web-scraping/seleniumscrapingtool", + "ar/tools/web-scraping/scrapegraphscrapetool", + "ar/tools/web-scraping/spidertool", + "ar/tools/web-scraping/browserbaseloadtool", + "ar/tools/web-scraping/hyperbrowserloadtool", + "ar/tools/web-scraping/stagehandtool", + "ar/tools/web-scraping/firecrawlcrawlwebsitetool", + "ar/tools/web-scraping/firecrawlscrapewebsitetool", + "ar/tools/web-scraping/oxylabsscraperstool", + "ar/tools/web-scraping/brightdata-tools" + ] + }, + { + "group": "البحث والاستكشاف", + "icon": "magnifying-glass", + "pages": [ + "ar/tools/search-research/overview", + "ar/tools/search-research/serperdevtool", + "ar/tools/search-research/bravesearchtool", + "ar/tools/search-research/exasearchtool", + "ar/tools/search-research/linkupsearchtool", + "ar/tools/search-research/githubsearchtool", + "ar/tools/search-research/websitesearchtool", + "ar/tools/search-research/codedocssearchtool", + "ar/tools/search-research/youtubechannelsearchtool", + "ar/tools/search-research/youtubevideosearchtool", + "ar/tools/search-research/tavilysearchtool", + "ar/tools/search-research/tavilyextractortool", + "ar/tools/search-research/arxivpapertool", + "ar/tools/search-research/serpapi-googlesearchtool", + "ar/tools/search-research/serpapi-googleshoppingtool", + "ar/tools/search-research/databricks-query-tool" + ] + }, + { + "group": "قواعد البيانات", + "icon": "database", + "pages": [ + "ar/tools/database-data/overview", + "ar/tools/database-data/mysqltool", + "ar/tools/database-data/pgsearchtool", + "ar/tools/database-data/snowflakesearchtool", + "ar/tools/database-data/nl2sqltool", + "ar/tools/database-data/qdrantvectorsearchtool", + "ar/tools/database-data/weaviatevectorsearchtool", + "ar/tools/database-data/mongodbvectorsearchtool", + "ar/tools/database-data/singlestoresearchtool" + ] + }, + { + "group": "الذكاء الاصطناعي والتعلّم الآلي", + "icon": "brain", + "pages": [ + "ar/tools/ai-ml/overview", + "ar/tools/ai-ml/dalletool", + "ar/tools/ai-ml/visiontool", + "ar/tools/ai-ml/aimindtool", + "ar/tools/ai-ml/llamaindextool", + "ar/tools/ai-ml/langchaintool", + "ar/tools/ai-ml/ragtool", + "ar/tools/ai-ml/codeinterpretertool" + ] + }, + { + "group": "التخزين السحابي", + "icon": "cloud", + "pages": [ + "ar/tools/cloud-storage/overview", + "ar/tools/cloud-storage/s3readertool", + "ar/tools/cloud-storage/s3writertool", + "ar/tools/cloud-storage/bedrockkbretriever" + ] + }, + { + "group": "Integrations", + "icon": "plug", + "pages": [ + "ar/tools/integration/overview", + "ar/tools/integration/bedrockinvokeagenttool", + "ar/tools/integration/crewaiautomationtool" + ] + }, + { + "group": "الأتمتة", + "icon": "bolt", + "pages": [ + "ar/tools/automation/overview", + "ar/tools/automation/apifyactorstool", + "ar/tools/automation/composiotool", + "ar/tools/automation/multiontool", + "ar/tools/automation/zapieractionstool" + ] + } + ] + }, + { + "group": "Observability", + "pages": [ + "ar/observability/tracing", + "ar/observability/overview", + "ar/observability/arize-phoenix", + "ar/observability/braintrust", + "ar/observability/datadog", + "ar/observability/galileo", + "ar/observability/langdb", + "ar/observability/langfuse", + "ar/observability/langtrace", + "ar/observability/maxim", + "ar/observability/mlflow", + "ar/observability/neatlogs", + "ar/observability/openlit", + "ar/observability/opik", + "ar/observability/patronus-evaluation", + "ar/observability/portkey", + "ar/observability/weave" + ] + }, + { + "group": "التعلّم", + "pages": [ + "ar/learn/overview", + "ar/learn/llm-selection-guide", + "ar/learn/conditional-tasks", + "ar/learn/coding-agents", + "ar/learn/create-custom-tools", + "ar/learn/custom-llm", + "ar/learn/custom-manager-agent", + "ar/learn/customizing-agents", + "ar/learn/dalle-image-generation", + "ar/learn/force-tool-output-as-result", + "ar/learn/hierarchical-process", + "ar/learn/human-input-on-execution", + "ar/learn/human-in-the-loop", + "ar/learn/human-feedback-in-flows", + "ar/learn/kickoff-async", + "ar/learn/kickoff-for-each", + "ar/learn/llm-connections", + "ar/learn/multimodal-agents", + "ar/learn/replay-tasks-from-latest-crew-kickoff", + "ar/learn/sequential-process", + "ar/learn/using-annotations", + "ar/learn/execution-hooks", + "ar/learn/llm-hooks", + "ar/learn/tool-hooks" + ] + }, + { + "group": "Telemetry", + "pages": [ + "ar/telemetry" + ] + } + ] + }, + { + "tab": "المؤسسات", + "icon": "briefcase", + "groups": [ + { + "group": "البدء", + "pages": [ + "ar/enterprise/introduction" + ] + }, + { + "group": "البناء", + "pages": [ + "ar/enterprise/features/automations", + "ar/enterprise/features/crew-studio", + "ar/enterprise/features/marketplace", + "ar/enterprise/features/agent-repositories", + "ar/enterprise/features/tools-and-integrations", + "ar/enterprise/features/pii-trace-redactions" + ] + }, + { + "group": "العمليات", + "pages": [ + "ar/enterprise/features/traces", + "ar/enterprise/features/webhook-streaming", + "ar/enterprise/features/hallucination-guardrail", + "ar/enterprise/features/flow-hitl-management" + ] + }, + { + "group": "الإدارة", + "pages": [ + "ar/enterprise/features/rbac" + ] + }, + { + "group": "التكاملات", + "pages": [ + "ar/enterprise/integrations/asana", + "ar/enterprise/integrations/box", + "ar/enterprise/integrations/clickup", + "ar/enterprise/integrations/github", + "ar/enterprise/integrations/gmail", + "ar/enterprise/integrations/google_calendar", + "ar/enterprise/integrations/google_contacts", + "ar/enterprise/integrations/google_docs", + "ar/enterprise/integrations/google_drive", + "ar/enterprise/integrations/google_sheets", + "ar/enterprise/integrations/google_slides", + "ar/enterprise/integrations/hubspot", + "ar/enterprise/integrations/jira", + "ar/enterprise/integrations/linear", + "ar/enterprise/integrations/microsoft_excel", + "ar/enterprise/integrations/microsoft_onedrive", + "ar/enterprise/integrations/microsoft_outlook", + "ar/enterprise/integrations/microsoft_sharepoint", + "ar/enterprise/integrations/microsoft_teams", + "ar/enterprise/integrations/microsoft_word", + "ar/enterprise/integrations/notion", + "ar/enterprise/integrations/salesforce", + "ar/enterprise/integrations/shopify", + "ar/enterprise/integrations/slack", + "ar/enterprise/integrations/stripe", + "ar/enterprise/integrations/zendesk" + ] + }, + { + "group": "How-To Guides", + "pages": [ + "ar/enterprise/guides/build-crew", + "ar/enterprise/guides/prepare-for-deployment", + "ar/enterprise/guides/deploy-to-amp", + "ar/enterprise/guides/private-package-registry", + "ar/enterprise/guides/kickoff-crew", + "ar/enterprise/guides/update-crew", + "ar/enterprise/guides/enable-crew-studio", + "ar/enterprise/guides/capture_telemetry_logs", + "ar/enterprise/guides/azure-openai-setup", + "ar/enterprise/guides/tool-repository", + "ar/enterprise/guides/custom-mcp-server", + "ar/enterprise/guides/react-component-export", + "ar/enterprise/guides/team-management", + "ar/enterprise/guides/human-in-the-loop", + "ar/enterprise/guides/webhook-automation" + ] + }, + { + "group": "المشغّلات", + "pages": [ + "ar/enterprise/guides/automation-triggers", + "ar/enterprise/guides/gmail-trigger", + "ar/enterprise/guides/google-calendar-trigger", + "ar/enterprise/guides/google-drive-trigger", + "ar/enterprise/guides/outlook-trigger", + "ar/enterprise/guides/onedrive-trigger", + "ar/enterprise/guides/microsoft-teams-trigger", + "ar/enterprise/guides/slack-trigger", + "ar/enterprise/guides/hubspot-trigger", + "ar/enterprise/guides/salesforce-trigger", + "ar/enterprise/guides/zapier-trigger" + ] + }, + { + "group": "موارد التعلّم", + "pages": [ + "ar/enterprise/resources/frequently-asked-questions" + ] + } + ] + }, + { + "tab": "API المرجع", + "icon": "magnifying-glass", + "groups": [ + { + "group": "البدء", + "pages": [ + "ar/api-reference/introduction", + "ar/api-reference/inputs", + "ar/api-reference/kickoff", + "ar/api-reference/resume", + "ar/api-reference/status" + ] + } + ] + }, + { + "tab": "أمثلة", + "icon": "code", + "groups": [ + { + "group": "أمثلة", + "pages": [ + "ar/examples/example", + "ar/examples/cookbooks" + ] + } + ] + }, + { + "tab": "التغييرات السجلات", + "icon": "clock", + "groups": [ + { + "group": "سجل التغييرات", + "pages": [ + "ar/changelog" + ] + } + ] + } + ] + } + ] } ] }, From eb255584b453ddba94949f7f2bacb0e6678e6d07 Mon Sep 17 00:00:00 2001 From: Greyson LaLonde Date: Wed, 25 Mar 2026 15:55:05 +0800 Subject: [PATCH 03/25] feat: add arabic language support to changelog and release tooling --- lib/devtools/src/crewai_devtools/cli.py | 25 +++++++++++++++++++++++-- 1 file changed, 23 insertions(+), 2 deletions(-) diff --git a/lib/devtools/src/crewai_devtools/cli.py b/lib/devtools/src/crewai_devtools/cli.py index 7a56f1f16..3917cead0 100644 --- a/lib/devtools/src/crewai_devtools/cli.py +++ b/lib/devtools/src/crewai_devtools/cli.py @@ -251,7 +251,7 @@ def add_docs_version(docs_json_path: Path, version: str) -> bool: return True -ChangelogLang = Literal["en", "pt-BR", "ko"] +ChangelogLang = Literal["en", "pt-BR", "ko", "ar"] _PT_BR_MONTHS: Final[dict[int, str]] = { 1: "jan", @@ -268,6 +268,21 @@ _PT_BR_MONTHS: Final[dict[int, str]] = { 12: "dez", } +_AR_MONTHS: Final[dict[int, str]] = { + 1: "يناير", + 2: "فبراير", + 3: "مارس", + 4: "أبريل", + 5: "مايو", + 6: "يونيو", + 7: "يوليو", + 8: "أغسطس", + 9: "سبتمبر", + 10: "أكتوبر", + 11: "نوفمبر", + 12: "ديسمبر", +} + _CHANGELOG_LOCALES: Final[ dict[ChangelogLang, dict[Literal["link_text", "language_name"], str]] ] = { @@ -283,6 +298,10 @@ _CHANGELOG_LOCALES: Final[ "link_text": "GitHub 릴리스 보기", "language_name": "Korean", }, + "ar": { + "link_text": "عرض الإصدار على GitHub", + "language_name": "Modern Standard Arabic", + }, } @@ -340,6 +359,8 @@ def _format_changelog_date(lang: ChangelogLang) -> str: return f"{now.year}년 {now.month}월 {now.day}일" if lang == "pt-BR": return f"{now.day:02d} {_PT_BR_MONTHS[now.month]} {now.year}" + if lang == "ar": + return f"{now.day} {_AR_MONTHS[now.month]} {now.year}" return now.strftime("%b %d, %Y") @@ -829,7 +850,7 @@ def _update_docs_and_create_pr( The docs branch name if a PR was created, None otherwise. """ docs_json_path = cwd / "docs" / "docs.json" - changelog_langs: list[ChangelogLang] = ["en", "pt-BR", "ko"] + changelog_langs: list[ChangelogLang] = ["en", "pt-BR", "ko", "ar"] if not dry_run: docs_files_staged: list[str] = [] From 185b69b83bc5d8c5d4a01afd74cac91e1fffaa24 Mon Sep 17 00:00:00 2001 From: Greyson LaLonde Date: Wed, 25 Mar 2026 16:13:55 +0800 Subject: [PATCH 04/25] docs: add CONTRIBUTING.md --- .github/CONTRIBUTING.md | 173 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 173 insertions(+) create mode 100644 .github/CONTRIBUTING.md 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). From 62bc27826d10aebea64403244c71f9277dddc07a Mon Sep 17 00:00:00 2001 From: nicoferdi96 Date: Wed, 25 Mar 2026 12:20:30 +0100 Subject: [PATCH 05/25] fix: agent memory saving MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fix: Add a remember_many() method to the MemoryScope class that delegates to self._memory.remember_many(...) with the scoped path, following the exact same pattern as the existing remember() method. Problem: When you pass memory=memory.scope("/agent/...") to an Agent, CrewAI's internal code calls remember_many() after every task to persist results. But MemoryScope never implemented remember_many() — only the parent Memory class has it. Symptom: [ERROR]: Failed to save kickoff result to memory: 'MemoryScope' object has no attribute 'remember_many' — memories are silently never saved after agent tasks. --- lib/crewai/src/crewai/memory/memory_scope.py | 24 ++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/lib/crewai/src/crewai/memory/memory_scope.py b/lib/crewai/src/crewai/memory/memory_scope.py index 6c252f9f2..2384600f4 100644 --- a/lib/crewai/src/crewai/memory/memory_scope.py +++ b/lib/crewai/src/crewai/memory/memory_scope.py @@ -79,6 +79,30 @@ class MemoryScope(BaseModel): private=private, ) + def remember_many( + self, + contents: list[str], + scope: str | None = "/", + categories: list[str] | None = None, + metadata: dict[str, Any] | None = None, + importance: float | None = None, + source: str | None = None, + private: bool = False, + agent_role: str | None = None, + ) -> list[MemoryRecord]: + """Remember multiple items; scope is relative to this scope's root.""" + path = self._scope_path(scope) + return self._memory.remember_many( + contents, + scope=path, + categories=categories, + metadata=metadata, + importance=importance, + source=source, + private=private, + agent_role=agent_role, + ) + def recall( self, query: str, From a49f9f982bd9dc8494d10bb5d6077e8c2a18e515 Mon Sep 17 00:00:00 2001 From: Greyson LaLonde Date: Wed, 25 Mar 2026 19:39:42 +0800 Subject: [PATCH 06/25] refactor: deduplicate sync/async task execution and kickoff in agent --- lib/crewai/src/crewai/agent/core.py | 727 +++++++++--------- .../tests/agents/test_agent_inject_date.py | 9 +- 2 files changed, 354 insertions(+), 382 deletions(-) diff --git a/lib/crewai/src/crewai/agent/core.py b/lib/crewai/src/crewai/agent/core.py index 868c14344..21b586cd7 100644 --- a/lib/crewai/src/crewai/agent/core.py +++ b/lib/crewai/src/crewai/agent/core.py @@ -1,8 +1,13 @@ +"""Core agent implementation for the CrewAI framework.""" + from __future__ import annotations import asyncio from collections.abc import Callable, Coroutine, Sequence +import concurrent.futures import contextvars +from datetime import datetime +import json from pathlib import Path import shutil import subprocess @@ -11,8 +16,10 @@ from typing import ( TYPE_CHECKING, Any, Literal, + NoReturn, cast, ) +import warnings from pydantic import ( BaseModel, @@ -44,6 +51,9 @@ from crewai.agents.cache.cache_handler import CacheHandler from crewai.agents.crew_agent_executor import CrewAgentExecutor from crewai.events.event_bus import crewai_event_bus from crewai.events.types.agent_events import ( + AgentExecutionCompletedEvent, + AgentExecutionErrorEvent, + AgentExecutionStartedEvent, LiteAgentExecutionCompletedEvent, LiteAgentExecutionErrorEvent, LiteAgentExecutionStartedEvent, @@ -58,6 +68,7 @@ from crewai.events.types.memory_events import ( MemoryRetrievalFailedEvent, MemoryRetrievalStartedEvent, ) +from crewai.events.types.skill_events import SkillActivatedEvent from crewai.experimental.agent_executor import AgentExecutor from crewai.knowledge.knowledge import Knowledge from crewai.knowledge.source.base_knowledge_source import BaseKnowledgeSource @@ -82,7 +93,7 @@ from crewai.utilities.constants import TRAINED_AGENTS_DATA_FILE, TRAINING_DATA_F from crewai.utilities.converter import Converter, ConverterError from crewai.utilities.env import get_env_context from crewai.utilities.guardrail import process_guardrail -from crewai.utilities.guardrail_types import GuardrailType +from crewai.utilities.guardrail_types import GuardrailCallable, GuardrailType from crewai.utilities.llm_utils import create_llm from crewai.utilities.prompts import Prompts, StandardPromptResult, SystemPromptResult from crewai.utilities.pydantic_schema_utils import generate_model_description @@ -263,13 +274,16 @@ class Agent(BaseAgent): ) @model_validator(mode="before") - def validate_from_repository(cls, v: Any) -> dict[str, Any] | None | Any: # noqa: N805 + @classmethod + def validate_from_repository(cls, v: Any) -> dict[str, Any] | None | Any: + """Merge repository agent config with provided values before validation.""" if v is not None and (from_repository := v.get("from_repository")): return load_agent_from_repository(from_repository) | v return v @model_validator(mode="after") def post_init_setup(self) -> Self: + """Initialize LLM, executor, code tools, and skills after model creation.""" self.llm = create_llm(self.llm) if self.function_calling_llm and not isinstance( self.function_calling_llm, BaseLLM @@ -284,10 +298,7 @@ class Agent(BaseAgent): self.set_skills() - # Handle backward compatibility: convert reasoning=True to planning_config if self.reasoning and self.planning_config is None: - import warnings - warnings.warn( "The 'reasoning' parameter is deprecated. Use 'planning_config=PlanningConfig()' instead.", DeprecationWarning, @@ -305,11 +316,13 @@ class Agent(BaseAgent): return self.planning_config is not None or self.planning def _setup_agent_executor(self) -> None: + """Initialize the agent executor with a default cache handler.""" if not self.cache_handler: self.cache_handler = CacheHandler() self.set_cache_handler(self.cache_handler) def set_knowledge(self, crew_embedder: EmbedderConfig | None = None) -> None: + """Initialize knowledge sources with the agent or crew embedder config.""" try: if self.embedder is None and crew_embedder: self.embedder = crew_embedder @@ -342,8 +355,6 @@ class Agent(BaseAgent): and activated). When provided, avoids redundant discovery per agent. """ from crewai.crew import Crew - from crewai.events.event_bus import crewai_event_bus - from crewai.events.types.skill_events import SkillActivatedEvent if resolved_crew_skills is None: crew_skills: list[Path | SkillModel] | None = ( @@ -421,6 +432,235 @@ class Agent(BaseAgent): and len(tools) > 0 ) + def _prepare_task_execution( + self, + task: Task, + context: str | None, + ) -> str: + """Prepare common setup for task execution shared by sync and async paths. + + Handles reasoning, date injection, prompt building, and memory retrieval. + + Args: + task: Task to execute. + context: Context to execute the task in. + + Returns: + The task prompt after memory retrieval, ready for knowledge lookup. + """ + get_env_context() + if self.executor_class is not AgentExecutor: + handle_reasoning(self, task) + + self._inject_date_to_task(task) + + if self.tools_handler: + self.tools_handler.last_used_tool = None + + task_prompt = task.prompt() + task_prompt = build_task_prompt_with_schema(task, task_prompt, self.i18n) + task_prompt = format_task_with_context(task_prompt, context, self.i18n) + return self._retrieve_memory_context(task, task_prompt) + + def _finalize_task_prompt( + self, + task_prompt: str, + tools: list[BaseTool] | None, + task: Task, + ) -> str: + """Apply skill context, tool preparation, and training data to the task prompt. + + Args: + task_prompt: The task prompt after memory and knowledge retrieval. + tools: Tools to use for the task. + task: Task to execute. + + Returns: + The fully prepared task prompt. + """ + task_prompt = append_skill_context(self, task_prompt) + prepare_tools(self, tools, task) + + return apply_training_data(self, task_prompt) + + def _retrieve_memory_context(self, task: Task, task_prompt: str) -> str: + """Retrieve memory context and append it to the task prompt. + + Args: + task: The task being executed. + task_prompt: The current task prompt. + + Returns: + The task prompt, potentially augmented with memory context. + """ + if not self._is_any_available_memory(): + return task_prompt + + crewai_event_bus.emit( + self, + event=MemoryRetrievalStartedEvent( + task_id=str(task.id) if task else None, + source_type="agent", + from_agent=self, + from_task=task, + ), + ) + + start_time = time.time() + memory = "" + + try: + unified_memory = getattr(self, "memory", None) or ( + getattr(self.crew, "_memory", None) if self.crew else None + ) + if unified_memory is not None: + query = task.description + matches = unified_memory.recall(query, limit=5) + if matches: + memory = "Relevant memories:\n" + "\n".join( + m.format() for m in matches + ) + if memory.strip() != "": + task_prompt += self.i18n.slice("memory").format(memory=memory) + + crewai_event_bus.emit( + self, + event=MemoryRetrievalCompletedEvent( + task_id=str(task.id) if task else None, + memory_content=memory, + retrieval_time_ms=(time.time() - start_time) * 1000, + source_type="agent", + from_agent=self, + from_task=task, + ), + ) + except Exception as e: + crewai_event_bus.emit( + self, + event=MemoryRetrievalFailedEvent( + task_id=str(task.id) if task else None, + source_type="agent", + from_agent=self, + from_task=task, + error=str(e), + ), + ) + + return task_prompt + + def _finalize_task_execution(self, task: Task, result: Any) -> Any: + """Finalize task execution with RPM cleanup, tool processing, and event emission. + + Args: + task: The task that was executed. + result: The raw execution result. + + Returns: + The processed result. + """ + if self.max_rpm and self._rpm_controller: + self._rpm_controller.stop_rpm_counter() + + result = process_tool_results(self, result) + + output_for_event = result + if ( + AgentResponseProtocol is not None + and isinstance(result, BaseModel) + and isinstance(result, AgentResponseProtocol) + ): + output_for_event = str(result.message) + elif not isinstance(result, str): + output_for_event = str(result) + + crewai_event_bus.emit( + self, + event=AgentExecutionCompletedEvent( + agent=self, task=task, output=output_for_event + ), + ) + + save_last_messages(self) + self._cleanup_mcp_clients() + + return result + + def _check_execution_error(self, e: Exception, task: Task) -> None: + """Check if an execution error should be re-raised immediately. + + Args: + e: The exception that occurred. + task: The task being executed. + + Raises: + Exception: If the error is from litellm, a passthrough, or retries are exhausted. + """ + if e.__class__.__module__.startswith("litellm"): + crewai_event_bus.emit( + self, + event=AgentExecutionErrorEvent( + agent=self, + task=task, + error=str(e), + ), + ) + raise e + if isinstance(e, _passthrough_exceptions): + raise + self._times_executed += 1 + if self._times_executed > self.max_retry_limit: + crewai_event_bus.emit( + self, + event=AgentExecutionErrorEvent( + agent=self, + task=task, + error=str(e), + ), + ) + raise e + + def _handle_execution_error( + self, + e: Exception, + task: Task, + context: str | None, + tools: list[BaseTool] | None, + ) -> Any: + """Handle execution errors with retry logic (sync path). + + Args: + e: The exception that occurred. + task: The task being executed. + context: Task context. + tools: Task tools. + + Returns: + Result from retried execution. + """ + self._check_execution_error(e, task) + return self.execute_task(task, context, tools) + + async def _handle_execution_error_async( + self, + e: Exception, + task: Task, + context: str | None, + tools: list[BaseTool] | None, + ) -> Any: + """Handle execution errors with retry logic (async path). + + Args: + e: The exception that occurred. + task: The task being executed. + context: Task context. + tools: Task tools. + + Returns: + Result from retried execution. + """ + self._check_execution_error(e, task) + return await self.aexecute_task(task, context, tools) + def execute_task( self, task: Task, @@ -442,71 +682,7 @@ class Agent(BaseAgent): ValueError: If the max execution time is not a positive integer. RuntimeError: If the agent execution fails for other reasons. """ - get_env_context() - # Only call handle_reasoning for legacy CrewAgentExecutor - # For AgentExecutor, planning is handled in AgentExecutor.generate_plan() - if self.executor_class is not AgentExecutor: - handle_reasoning(self, task) - - self._inject_date_to_task(task) - - if self.tools_handler: - self.tools_handler.last_used_tool = None - - task_prompt = task.prompt() - task_prompt = build_task_prompt_with_schema(task, task_prompt, self.i18n) - task_prompt = format_task_with_context(task_prompt, context, self.i18n) - - if self._is_any_available_memory(): - crewai_event_bus.emit( - self, - event=MemoryRetrievalStartedEvent( - task_id=str(task.id) if task else None, - source_type="agent", - from_agent=self, - from_task=task, - ), - ) - - start_time = time.time() - memory = "" - - try: - unified_memory = getattr(self, "memory", None) or ( - getattr(self.crew, "_memory", None) if self.crew else None - ) - if unified_memory is not None: - query = task.description - matches = unified_memory.recall(query, limit=5) - if matches: - memory = "Relevant memories:\n" + "\n".join( - m.format() for m in matches - ) - if memory.strip() != "": - task_prompt += self.i18n.slice("memory").format(memory=memory) - - crewai_event_bus.emit( - self, - event=MemoryRetrievalCompletedEvent( - task_id=str(task.id) if task else None, - memory_content=memory, - retrieval_time_ms=(time.time() - start_time) * 1000, - source_type="agent", - from_agent=self, - from_task=task, - ), - ) - except Exception as e: - crewai_event_bus.emit( - self, - event=MemoryRetrievalFailedEvent( - task_id=str(task.id) if task else None, - source_type="agent", - from_agent=self, - from_task=task, - error=str(e), - ), - ) + task_prompt = self._prepare_task_execution(task, context) knowledge_config = get_knowledge_config(self) task_prompt = handle_knowledge_retrieval( @@ -518,16 +694,7 @@ class Agent(BaseAgent): self.crew.query_knowledge if self.crew else lambda *a, **k: None, ) - task_prompt = append_skill_context(self, task_prompt) - - prepare_tools(self, tools, task) - task_prompt = apply_training_data(self, task_prompt) - - from crewai.events.types.agent_events import ( - AgentExecutionCompletedEvent, - AgentExecutionErrorEvent, - AgentExecutionStartedEvent, - ) + task_prompt = self._finalize_task_prompt(task_prompt, tools, task) try: crewai_event_bus.emit( @@ -559,57 +726,9 @@ class Agent(BaseAgent): ) raise e except Exception as e: - if e.__class__.__module__.startswith("litellm"): - crewai_event_bus.emit( - self, - event=AgentExecutionErrorEvent( - agent=self, - task=task, - error=str(e), - ), - ) - raise e - if isinstance(e, _passthrough_exceptions): - raise - self._times_executed += 1 - if self._times_executed > self.max_retry_limit: - crewai_event_bus.emit( - self, - event=AgentExecutionErrorEvent( - agent=self, - task=task, - error=str(e), - ), - ) - raise e - result = self.execute_task(task, context, tools) + result = self._handle_execution_error(e, task, context, tools) - if self.max_rpm and self._rpm_controller: - self._rpm_controller.stop_rpm_counter() - - result = process_tool_results(self, result) - - output_for_event = result - if ( - AgentResponseProtocol is not None - and isinstance(result, BaseModel) - and isinstance(result, AgentResponseProtocol) - ): - output_for_event = str(result.message) - elif not isinstance(result, str): - output_for_event = str(result) - - crewai_event_bus.emit( - self, - event=AgentExecutionCompletedEvent( - agent=self, task=task, output=output_for_event - ), - ) - - save_last_messages(self) - self._cleanup_mcp_clients() - - return result + return self._finalize_task_execution(task, result) def _execute_with_timeout(self, task_prompt: str, task: Task, timeout: int) -> Any: """Execute a task with a timeout. @@ -626,8 +745,6 @@ class Agent(BaseAgent): TimeoutError: If execution exceeds the timeout. RuntimeError: If execution fails for other reasons. """ - import concurrent.futures - ctx = contextvars.copy_context() with concurrent.futures.ThreadPoolExecutor() as executor: future = executor.submit( @@ -691,85 +808,14 @@ class Agent(BaseAgent): ValueError: If the max execution time is not a positive integer. RuntimeError: If the agent execution fails for other reasons. """ - if self.executor_class is not AgentExecutor: - handle_reasoning( - self, task - ) # we need this till CrewAgentExecutor migrates to AgentExecutor - self._inject_date_to_task(task) - - if self.tools_handler: - self.tools_handler.last_used_tool = None - - task_prompt = task.prompt() - task_prompt = build_task_prompt_with_schema(task, task_prompt, self.i18n) - task_prompt = format_task_with_context(task_prompt, context, self.i18n) - - if self._is_any_available_memory(): - crewai_event_bus.emit( - self, - event=MemoryRetrievalStartedEvent( - task_id=str(task.id) if task else None, - source_type="agent", - from_agent=self, - from_task=task, - ), - ) - - start_time = time.time() - memory = "" - - try: - unified_memory = getattr(self, "memory", None) or ( - getattr(self.crew, "_memory", None) if self.crew else None - ) - if unified_memory is not None: - query = task.description - matches = unified_memory.recall(query, limit=5) - if matches: - memory = "Relevant memories:\n" + "\n".join( - m.format() for m in matches - ) - if memory.strip() != "": - task_prompt += self.i18n.slice("memory").format(memory=memory) - - crewai_event_bus.emit( - self, - event=MemoryRetrievalCompletedEvent( - task_id=str(task.id) if task else None, - memory_content=memory, - retrieval_time_ms=(time.time() - start_time) * 1000, - source_type="agent", - from_agent=self, - from_task=task, - ), - ) - except Exception as e: - crewai_event_bus.emit( - self, - event=MemoryRetrievalFailedEvent( - task_id=str(task.id) if task else None, - source_type="agent", - from_agent=self, - from_task=task, - error=str(e), - ), - ) + task_prompt = self._prepare_task_execution(task, context) knowledge_config = get_knowledge_config(self) task_prompt = await ahandle_knowledge_retrieval( self, task, task_prompt, knowledge_config ) - task_prompt = append_skill_context(self, task_prompt) - - prepare_tools(self, tools, task) - task_prompt = apply_training_data(self, task_prompt) - - from crewai.events.types.agent_events import ( - AgentExecutionCompletedEvent, - AgentExecutionErrorEvent, - AgentExecutionStartedEvent, - ) + task_prompt = self._finalize_task_prompt(task_prompt, tools, task) try: crewai_event_bus.emit( @@ -801,57 +847,9 @@ class Agent(BaseAgent): ) raise e except Exception as e: - if e.__class__.__module__.startswith("litellm"): - crewai_event_bus.emit( - self, - event=AgentExecutionErrorEvent( - agent=self, - task=task, - error=str(e), - ), - ) - raise e - if isinstance(e, _passthrough_exceptions): - raise - self._times_executed += 1 - if self._times_executed > self.max_retry_limit: - crewai_event_bus.emit( - self, - event=AgentExecutionErrorEvent( - agent=self, - task=task, - error=str(e), - ), - ) - raise e - result = await self.aexecute_task(task, context, tools) + result = await self._handle_execution_error_async(e, task, context, tools) - if self.max_rpm and self._rpm_controller: - self._rpm_controller.stop_rpm_counter() - - result = process_tool_results(self, result) - - output_for_event = result - if ( - AgentResponseProtocol is not None - and isinstance(result, BaseModel) - and isinstance(result, AgentResponseProtocol) - ): - output_for_event = str(result.message) - elif not isinstance(result, str): - output_for_event = str(result) - - crewai_event_bus.emit( - self, - event=AgentExecutionCompletedEvent( - agent=self, task=task, output=output_for_event - ), - ) - - save_last_messages(self) - self._cleanup_mcp_clients() - - return result + return self._finalize_task_execution(task, result) async def _aexecute_with_timeout( self, task_prompt: str, task: Task, timeout: int @@ -904,17 +902,19 @@ class Agent(BaseAgent): ) return result["output"] - def create_agent_executor( - self, tools: list[BaseTool] | None = None, task: Task | None = None - ) -> None: - """Create an agent executor for the agent. + def _build_execution_prompt( + self, raw_tools: list[BaseTool] + ) -> tuple[ + SystemPromptResult | StandardPromptResult, list[str], Callable[[], bool] | None + ]: + """Build the execution prompt, stop words, and RPM limit function. + + Args: + raw_tools: The raw tools available to the agent. Returns: - An instance of the CrewAgentExecutor class. + A tuple of (prompt, stop_words, rpm_limit_fn). """ - raw_tools: list[BaseTool] = tools or self.tools or [] - parsed_tools = parse_tools(raw_tools) - use_native_tool_calling = self._supports_native_tool_calling(raw_tools) prompt = Prompts( @@ -929,7 +929,6 @@ class Agent(BaseAgent): ).task_execution() stop_words = [self.i18n.slice("observation")] - if self.response_template: stop_words.append( self.response_template.split("{{ .Response }}")[1].strip() @@ -939,6 +938,21 @@ class Agent(BaseAgent): self._rpm_controller.check_or_wait if self._rpm_controller else None ) + return prompt, stop_words, rpm_limit_fn + + def create_agent_executor( + self, tools: list[BaseTool] | None = None, task: Task | None = None + ) -> None: + """Create an agent executor for the agent. + + Returns: + An instance of the CrewAgentExecutor class. + """ + raw_tools: list[BaseTool] = tools or self.tools or [] + parsed_tools = parse_tools(raw_tools) + + prompt, stop_words, rpm_limit_fn = self._build_execution_prompt(raw_tools) + if self.agent_executor is not None: self._update_executor_parameters( task=task, @@ -1052,17 +1066,18 @@ class Agent(BaseAgent): @staticmethod def get_multimodal_tools() -> Sequence[BaseTool]: + """Return tools for multimodal agent capabilities.""" from crewai.tools.agent_tools.add_image_tool import AddImageTool return [AddImageTool()] def get_code_execution_tools(self) -> list[CodeInterpreterTool]: + """Return code interpreter tools based on the agent's execution mode.""" try: from crewai_tools import ( CodeInterpreterTool, ) - # Set the unsafe_mode based on the code_execution_mode attribute unsafe_mode = self.code_execution_mode == "unsafe" return [CodeInterpreterTool(unsafe_mode=unsafe_mode)] except ModuleNotFoundError: @@ -1075,6 +1090,7 @@ class Agent(BaseAgent): def get_output_converter( llm: BaseLLM, text: str, model: type[BaseModel], instructions: str ) -> Converter: + """Create a Converter instance for transforming LLM output to a structured model.""" return Converter(llm=llm, text=text, model=model, instructions=instructions) def _training_handler(self, task_prompt: str) -> str: @@ -1124,8 +1140,6 @@ class Agent(BaseAgent): def _inject_date_to_task(self, task: Task) -> None: """Inject the current date into the task description if inject_date is enabled.""" if self.inject_date: - from datetime import datetime - try: valid_format_codes = [ "%Y", @@ -1159,7 +1173,7 @@ class Agent(BaseAgent): try: subprocess.run( # noqa: S603 - [docker_path, "info"], + [str(docker_path), "info"], check=True, stdout=subprocess.PIPE, stderr=subprocess.PIPE, @@ -1187,6 +1201,7 @@ class Agent(BaseAgent): return self.security_config.fingerprint def set_fingerprint(self, fingerprint: Fingerprint) -> None: + """Set the agent's security fingerprint.""" self.security_config.fingerprint = fingerprint @property @@ -1228,15 +1243,11 @@ class Agent(BaseAgent): return None try: - rewritten_query = self.llm.call( - [ - { - "role": "system", - "content": rewriter_prompt, - }, - {"role": "user", "content": query}, - ] - ) + messages: list[LLMMessage] = [ + {"role": "system", "content": rewriter_prompt}, + {"role": "user", "content": query}, + ] + rewritten_query = self.llm.call(messages) crewai_event_bus.emit( self, event=KnowledgeQueryCompletedEvent( @@ -1277,7 +1288,6 @@ class Agent(BaseAgent): Returns: Tuple of (executor, inputs, agent_info, parsed_tools) ready for execution. """ - # Process platform apps and MCP tools if self.apps: platform_tools = self.get_platform_tools(self.apps) if platform_tools: @@ -1291,7 +1301,6 @@ class Agent(BaseAgent): self.tools = [] self.tools.extend(mcps) - # Prepare tools raw_tools: list[BaseTool] = self.tools or [] # Inject memory tools for standalone kickoff (crew path handles its own) @@ -1308,7 +1317,6 @@ class Agent(BaseAgent): parsed_tools = parse_tools(raw_tools) - # Build agent_info for backward-compatible event emission agent_info = { "id": self.id, "role": self.role, @@ -1318,35 +1326,9 @@ class Agent(BaseAgent): "verbose": self.verbose, } - # Build prompt for standalone execution - use_native_tool_calling = self._supports_native_tool_calling(raw_tools) - prompt = Prompts( - agent=self, - has_tools=len(raw_tools) > 0, - use_native_tool_calling=use_native_tool_calling, - i18n=self.i18n, - use_system_prompt=self.use_system_prompt, - system_template=self.system_template, - prompt_template=self.prompt_template, - response_template=self.response_template, - ).task_execution() + prompt, stop_words, rpm_limit_fn = self._build_execution_prompt(raw_tools) - # Prepare stop words - stop_words = [self.i18n.slice("observation")] - if self.response_template: - stop_words.append( - self.response_template.split("{{ .Response }}")[1].strip() - ) - - # Get RPM limit function - rpm_limit_fn = ( - self._rpm_controller.check_or_wait if self._rpm_controller else None - ) - - # Create the executor for standalone mode (no crew, no task) executor = AgentExecutor( - task=None, - crew=None, llm=cast(BaseLLM, self.llm), agent=self, prompt=prompt, @@ -1425,7 +1407,6 @@ class Agent(BaseAgent): formatted_messages = append_skill_context(self, formatted_messages) - # Build the input dict for the executor inputs: dict[str, Any] = { "input": formatted_messages, "tool_names": get_tool_names(parsed_tools), @@ -1487,36 +1468,65 @@ class Agent(BaseAgent): ) output = self._execute_and_build_output(executor, inputs, response_format) - if self.guardrail is not None: - output = self._process_kickoff_guardrail( - output=output, - executor=executor, - inputs=inputs, - response_format=response_format, - ) - - # Save to memory after execution (passive save) - self._save_kickoff_to_memory(messages, output.raw) - - crewai_event_bus.emit( - self, - event=LiteAgentExecutionCompletedEvent( - agent_info=agent_info, - output=output.raw, - ), + return self._finalize_kickoff( + output, executor, inputs, response_format, messages, agent_info ) - return output - except Exception as e: - crewai_event_bus.emit( - self, - event=LiteAgentExecutionErrorEvent( - agent_info=agent_info, - error=str(e), - ), + self._emit_kickoff_error(agent_info, e) + + def _finalize_kickoff( + self, + output: LiteAgentOutput, + executor: AgentExecutor, + inputs: dict[str, str], + response_format: type[Any] | None, + messages: str | list[LLMMessage], + agent_info: dict[str, Any], + ) -> LiteAgentOutput: + """Apply guardrails, save to memory, and emit completion event. + + Args: + output: The execution output. + executor: The agent executor. + inputs: The execution inputs. + response_format: Optional response format. + messages: The original messages. + agent_info: Agent metadata for events. + + Returns: + The finalized output. + """ + if self.guardrail is not None: + output = self._process_kickoff_guardrail( + output=output, + executor=executor, + inputs=inputs, + response_format=response_format, ) - raise + + self._save_kickoff_to_memory(messages, output.raw) + + crewai_event_bus.emit( + self, + event=LiteAgentExecutionCompletedEvent( + agent_info=agent_info, + output=output.raw, + ), + ) + + return output + + def _emit_kickoff_error(self, agent_info: dict[str, Any], e: Exception) -> NoReturn: + """Emit a kickoff error event and re-raise.""" + crewai_event_bus.emit( + self, + event=LiteAgentExecutionErrorEvent( + agent_info=agent_info, + error=str(e), + ), + ) + raise e def _save_kickoff_to_memory( self, messages: str | list[LLMMessage], output_text: str @@ -1562,11 +1572,8 @@ class Agent(BaseAgent): Returns: LiteAgentOutput with raw output, formatted result, and metrics. """ - import json - output = result.get("output", "") - # Handle response format conversion formatted_result: BaseModel | None = None raw_output: str @@ -1583,7 +1590,7 @@ class Agent(BaseAgent): ) converter = Converter( - llm=self.llm, + llm=cast(BaseLLM, self.llm), text=raw_output, model=response_format, instructions=instructions, @@ -1597,7 +1604,6 @@ class Agent(BaseAgent): else: raw_output = str(output) if not isinstance(output, str) else output - # Get token usage metrics if isinstance(self.llm, BaseLLM): usage_metrics = self.llm.get_token_usage_summary() else: @@ -1665,9 +1671,6 @@ class Agent(BaseAgent): Returns: Validated/updated output. """ - from crewai.utilities.guardrail_types import GuardrailCallable - - # Ensure guardrail is callable guardrail_callable: GuardrailCallable if isinstance(self.guardrail, str): from crewai.tasks.llm_guardrail import LLMGuardrail @@ -1697,16 +1700,13 @@ class Agent(BaseAgent): f"Last error: {guardrail_result.error}" ) - # Add feedback and re-execute executor._append_message_to_state( guardrail_result.error or "Guardrail validation failed", role="user", ) - # Re-execute and build new output output = self._execute_and_build_output(executor, inputs, response_format) - # Recursively retry guardrail return self._process_kickoff_guardrail( output=output, executor=executor, @@ -1715,7 +1715,6 @@ class Agent(BaseAgent): retry_count=retry_count + 1, ) - # Apply guardrail result if available if guardrail_result.result is not None: if isinstance(guardrail_result.result, str): output.raw = guardrail_result.result @@ -1765,37 +1764,12 @@ class Agent(BaseAgent): output = await self._execute_and_build_output_async( executor, inputs, response_format ) - - if self.guardrail is not None: - output = self._process_kickoff_guardrail( - output=output, - executor=executor, - inputs=inputs, - response_format=response_format, - ) - - # Save to memory after async execution (passive save) - self._save_kickoff_to_memory(messages, output.raw) - - crewai_event_bus.emit( - self, - event=LiteAgentExecutionCompletedEvent( - agent_info=agent_info, - output=output.raw, - ), + return self._finalize_kickoff( + output, executor, inputs, response_format, messages, agent_info ) - return output - except Exception as e: - crewai_event_bus.emit( - self, - event=LiteAgentExecutionErrorEvent( - agent_info=agent_info, - error=str(e), - ), - ) - raise + self._emit_kickoff_error(agent_info, e) async def akickoff( self, @@ -1816,7 +1790,6 @@ class Agent(BaseAgent): return await self.kickoff_async(messages, response_format, input_files) -# Rebuild Agent model to resolve A2A type forward references try: from crewai.a2a.config import ( A2AClientConfig as _A2AClientConfig, diff --git a/lib/crewai/tests/agents/test_agent_inject_date.py b/lib/crewai/tests/agents/test_agent_inject_date.py index 7ff6b1440..0ca9da18f 100644 --- a/lib/crewai/tests/agents/test_agent_inject_date.py +++ b/lib/crewai/tests/agents/test_agent_inject_date.py @@ -4,13 +4,15 @@ from unittest.mock import patch from crewai.agent import Agent from crewai.task import Task +MOCK_TARGET = "crewai.agent.core.datetime" + def test_agent_inject_date(): """Test that the inject_date flag injects the current date into the task. Tests that when inject_date=True, the current date is added to the task description. """ - with patch("datetime.datetime") as mock_datetime: + with patch(MOCK_TARGET) as mock_datetime: mock_datetime.now.return_value = datetime(2025, 1, 1) agent = Agent( @@ -26,7 +28,6 @@ def test_agent_inject_date(): agent=agent, ) - # Store original description original_description = task.description agent._inject_date_to_task(task) @@ -44,7 +45,6 @@ def test_agent_without_inject_date(): role="test_agent", goal="test_goal", backstory="test_backstory", - # inject_date is False by default ) task = Task( @@ -65,7 +65,7 @@ def test_agent_inject_date_custom_format(): Tests that when inject_date=True with a custom date_format, the date is formatted correctly. """ - with patch("datetime.datetime") as mock_datetime: + with patch(MOCK_TARGET) as mock_datetime: mock_datetime.now.return_value = datetime(2025, 1, 1) agent = Agent( @@ -82,7 +82,6 @@ def test_agent_inject_date_custom_format(): agent=agent, ) - # Store original description original_description = task.description agent._inject_date_to_task(task) From 6f58b63e5dc406007596e5f62159d400be265822 Mon Sep 17 00:00:00 2001 From: Greyson LaLonde Date: Wed, 25 Mar 2026 19:59:14 +0800 Subject: [PATCH 07/25] feat: add docs-check command to analyze changes and generate docs with translations --- lib/devtools/pyproject.toml | 1 + lib/devtools/src/crewai_devtools/cli.py | 2 + .../src/crewai_devtools/docs_check.py | 476 ++++++++++++++++++ 3 files changed, 479 insertions(+) create mode 100644 lib/devtools/src/crewai_devtools/docs_check.py diff --git a/lib/devtools/pyproject.toml b/lib/devtools/pyproject.toml index af557b413..4c5f2d605 100644 --- a/lib/devtools/pyproject.toml +++ b/lib/devtools/pyproject.toml @@ -22,6 +22,7 @@ dependencies = [ bump-version = "crewai_devtools.cli:bump" tag = "crewai_devtools.cli:tag" release = "crewai_devtools.cli:release" +docs-check = "crewai_devtools.docs_check:docs_check" devtools = "crewai_devtools.cli:main" [build-system] diff --git a/lib/devtools/src/crewai_devtools/cli.py b/lib/devtools/src/crewai_devtools/cli.py index 3917cead0..ca95a0e9c 100644 --- a/lib/devtools/src/crewai_devtools/cli.py +++ b/lib/devtools/src/crewai_devtools/cli.py @@ -16,6 +16,7 @@ from rich.markdown import Markdown from rich.panel import Panel from rich.prompt import Confirm +from crewai_devtools.docs_check import docs_check from crewai_devtools.prompts import RELEASE_NOTES_PROMPT, TRANSLATE_RELEASE_NOTES_PROMPT @@ -1353,6 +1354,7 @@ def release(version: str, dry_run: bool, no_edit: bool) -> None: cli.add_command(bump) cli.add_command(tag) cli.add_command(release) +cli.add_command(docs_check) def main() -> None: diff --git a/lib/devtools/src/crewai_devtools/docs_check.py b/lib/devtools/src/crewai_devtools/docs_check.py new file mode 100644 index 000000000..8a4432fb5 --- /dev/null +++ b/lib/devtools/src/crewai_devtools/docs_check.py @@ -0,0 +1,476 @@ +"""Analyze code changes and generate/update documentation with translations. + +Examines a git diff, determines what documentation changes are needed, +and optionally generates English docs + translations for all supported languages. +""" + +from __future__ import annotations + +from pathlib import Path +import subprocess +from typing import Final, Literal + +import click +from dotenv import load_dotenv +from openai import OpenAI +from pydantic import BaseModel, Field +from rich.console import Console +from rich.panel import Panel +from rich.table import Table + + +load_dotenv() + +console = Console() + +DocLang = Literal["en", "ar", "ko", "pt-BR"] +_TRANSLATION_LANGS: Final[list[DocLang]] = ["ar", "ko", "pt-BR"] + +_LANGUAGE_NAMES: Final[dict[DocLang, str]] = { + "en": "English", + "ar": "Modern Standard Arabic", + "ko": "Korean", + "pt-BR": "Brazilian Portuguese", +} + + +# --- Structured output models --- + + +class DocAction(BaseModel): + """A single documentation action to take.""" + + action: Literal["create", "update"] = Field( + description="Whether to create a new page or update an existing one." + ) + file: str = Field( + description="Target docs path relative to docs/en/ (e.g., 'concepts/skills.mdx')." + ) + reason: str = Field(description="Why this documentation change is needed.") + section: str | None = Field( + default=None, + description="For updates, which section of the existing doc needs changing.", + ) + + +class DocsAnalysis(BaseModel): + """Analysis of what documentation changes are needed for a code diff.""" + + needs_docs: bool = Field( + description="Whether any documentation changes are needed." + ) + summary: str = Field(description="One-line summary of documentation impact.") + actions: list[DocAction] = Field( + default_factory=list, + description="List of documentation actions to take.", + ) + + +# --- Prompts --- + +_ANALYZE_SYSTEM: Final[str] = """\ +You are a documentation analyst for the CrewAI open-source framework. + +Analyze git diffs and determine what documentation changes are needed. + +Consider these categories: +- New features (new classes, decorators, CLI commands) → may need a new doc page or section +- API changes (new parameters, changed signatures) → update existing docs +- Configuration changes (new settings, env vars) → update relevant config docs +- Deprecations or removals → update affected docs +- Bug fixes with user-visible behavior changes → may need doc clarification + +Only flag changes that affect the PUBLIC API or user-facing behavior. +Do NOT flag internal refactors, test changes, CI changes, or type annotation fixes.""" + +_ANALYZE_USER: Final[str] = "Analyze the following git diff:\n\n" + +_GENERATE_DOC_PROMPT: Final[str] = """\ +You are a technical writer for the CrewAI open-source framework. + +Generate documentation in MDX format for the following change. + +Rules: +- Use the same style and structure as existing CrewAI docs +- Start with YAML frontmatter: title, description, icon (optional) +- Use MDX components: , , , , , , \ +, , , , , , +- Include code examples in Python +- Keep prose concise and technical +- Do not include translator notes or meta-commentary + +Context about the change: +{reason} + +{existing_content} + +{diff_context} + +Generate the full MDX file content:""" + +_UPDATE_DOC_PROMPT: Final[str] = """\ +You are a technical writer for the CrewAI open-source framework. + +Update the following existing documentation based on the code changes described below. + +Rules: +- Preserve the overall structure and style of the existing document +- Only modify sections that are affected by the changes +- Keep all MDX components, frontmatter structure, and code formatting intact +- Do not remove existing content unless it is now incorrect +- Add new sections where appropriate + +Change description: +{reason} + +Section to update: {section} + +Existing document: +{existing_content} + +Code diff context: +{diff_context} + +Generate the complete updated MDX file:""" + +_TRANSLATE_DOC_PROMPT: Final[str] = """\ +Translate the following MDX documentation into {language}. + +Rules: +- Translate ALL prose text (headings, descriptions, paragraphs, list items) +- Keep all MDX/JSX syntax, component tags, frontmatter keys, code blocks, \ +URLs, and variable names in English +- Translate frontmatter values (title, description, sidebarTitle) +- Keep technical terms like Agent, Crew, Task, Flow, LLM, API, CLI, MCP \ +in English as appropriate for {language} technical writing +- Keep code examples exactly as-is +- Do NOT add translator notes or comments +- Internal doc links should use /{lang_code}/ prefix instead of /en/ + +Document to translate: +{content}""" + + +def _run_git(args: list[str]) -> str: + """Run a git command and return stdout.""" + result = subprocess.run( # noqa: S603 + ["git", *args], # noqa: S607 + capture_output=True, + text=True, + check=True, + ) + return result.stdout.strip() + + +def _get_diff(base: str) -> str: + """Get the git diff against a base ref.""" + return _run_git(["diff", base, "--", "lib/"]) + + +def _get_openai_client() -> OpenAI: + """Create an OpenAI client.""" + return OpenAI() + + +def _analyze_diff(diff: str, client: OpenAI) -> DocsAnalysis: + """Analyze a git diff and determine what docs are needed. + + Args: + diff: Git diff output. + client: OpenAI client. + + Returns: + Structured analysis result with actions. + """ + response = client.beta.chat.completions.parse( + model="gpt-4o-mini", + messages=[ + {"role": "system", "content": _ANALYZE_SYSTEM}, + {"role": "user", "content": _ANALYZE_USER + diff[:50000]}, + ], + temperature=0.2, + response_format=DocsAnalysis, + ) + return response.choices[0].message.parsed or DocsAnalysis( + needs_docs=False, summary="Analysis failed." + ) + + +def _generate_doc( + reason: str, + existing_content: str | None, + diff_context: str, + client: OpenAI, +) -> str: + """Generate a new documentation page. + + Args: + reason: Why this doc is needed. + existing_content: Existing doc content for style reference, or None. + diff_context: The code diff to document. + client: OpenAI client. + + Returns: + Generated MDX content. + """ + context = "" + if existing_content: + context = f"Reference existing doc for style:\n{existing_content[:5000]}" + + diff_section = "" + if diff_context: + diff_section = f"Code changes:\n{diff_context[:10000]}" + + prompt = _GENERATE_DOC_PROMPT.format( + reason=reason, + existing_content=context, + diff_context=diff_section, + ) + + response = client.chat.completions.create( + model="gpt-4o", + messages=[ + { + "role": "system", + "content": "You are a technical writer. Output only MDX content.", + }, + {"role": "user", "content": prompt}, + ], + temperature=0.3, + ) + return response.choices[0].message.content or "" + + +def _update_doc( + reason: str, + section: str, + existing_content: str, + diff_context: str, + client: OpenAI, +) -> str: + """Update an existing documentation page. + + Args: + reason: Why this update is needed. + section: Which section to update. + existing_content: Current doc content. + diff_context: Relevant portion of the diff. + client: OpenAI client. + + Returns: + Updated MDX content. + """ + prompt = _UPDATE_DOC_PROMPT.format( + reason=reason, + section=section, + existing_content=existing_content, + diff_context=diff_context[:10000], + ) + + response = client.chat.completions.create( + model="gpt-4o", + messages=[ + { + "role": "system", + "content": "You are a technical writer. Output only the complete updated MDX file.", + }, + {"role": "user", "content": prompt}, + ], + temperature=0.3, + ) + return response.choices[0].message.content or "" + + +def _translate_doc( + content: str, + lang: DocLang, + client: OpenAI, +) -> str: + """Translate an English doc to another language. + + Args: + content: English MDX content. + lang: Target language code. + client: OpenAI client. + + Returns: + Translated MDX content. + """ + language_name = _LANGUAGE_NAMES[lang] + prompt = _TRANSLATE_DOC_PROMPT.format( + language=language_name, + lang_code=lang, + content=content, + ) + + response = client.chat.completions.create( + model="gpt-4o-mini", + messages=[ + { + "role": "system", + "content": f"You are a professional translator. Translate technical documentation into {language_name}. Output only the translated MDX.", + }, + {"role": "user", "content": prompt}, + ], + temperature=0.3, + ) + return response.choices[0].message.content or "" + + +def _print_analysis(analysis: DocsAnalysis) -> None: + """Print the analysis results.""" + if not analysis.needs_docs: + console.print("[green]No documentation changes needed.[/green]") + return + + console.print( + Panel(analysis.summary, title="Documentation Impact", border_style="yellow") + ) + + table = Table(title="Required Actions") + table.add_column("Action", style="cyan") + table.add_column("File", style="white") + table.add_column("Reason", style="dim") + + for action in analysis.actions: + table.add_row(action.action, action.file, action.reason) + + console.print(table) + + +@click.command("docs-check") +@click.option( + "--base", + default="main", + help="Base ref to diff against (default: main).", +) +@click.option( + "--write", + is_flag=True, + help="Generate/update docs and translations (not just analyze).", +) +@click.option( + "--dry-run", + is_flag=True, + help="Show what would be written without writing files.", +) +def docs_check(base: str, write: bool, dry_run: bool) -> None: + """Analyze code changes and determine if documentation is needed. + + Examines the diff between the current branch and --base, classifies + changes, and reports what documentation should be created or updated. + + With --write, generates English docs and translates to all supported + languages (ar, ko, pt-BR). + + Args: + base: Base git ref to diff against. + write: Whether to generate/update docs. + dry_run: Show what would be done without writing. + """ + cwd = Path.cwd() + docs_dir = cwd / "docs" + + with console.status("[cyan]Getting diff..."): + diff = _get_diff(base) + + if not diff: + console.print("[green]No code changes found.[/green]") + return + + with console.status("[cyan]Analyzing changes..."): + client = _get_openai_client() + analysis = _analyze_diff(diff, client) + + _print_analysis(analysis) + + if not analysis.needs_docs or not analysis.actions: + return + + if not write: + console.print( + "\n[dim]Run with --write to generate docs, " + "or --write --dry-run to preview.[/dim]" + ) + return + + for action_item in analysis.actions: + if action_item.action not in ("create", "update") or not action_item.file: + continue + + rel_path = action_item.file + en_path = (docs_dir / "en" / rel_path).resolve() + if not en_path.is_relative_to(docs_dir.resolve()): + console.print(f" [red]✗ Skipping unsafe path: {rel_path!r}[/red]") + continue + console.print(f"\n[bold]Processing:[/bold] {rel_path}") + + content: str = "" + + if action_item.action == "create": + if en_path.exists(): + console.print(" [yellow]⚠[/yellow] Already exists, skipping create") + continue + + with console.status(f" [cyan]Generating {rel_path}..."): + ref_content = None + parent = en_path.parent + if parent.exists(): + siblings = list(parent.glob("*.mdx")) + if siblings: + ref_content = siblings[0].read_text() + content = _generate_doc(action_item.reason, ref_content, diff, client) + + if dry_run: + console.print(f" [dim][DRY RUN] Would create {en_path}[/dim]") + console.print(f" [dim]Preview: {content[:200]}...[/dim]") + else: + en_path.parent.mkdir(parents=True, exist_ok=True) + en_path.write_text(content) + console.print(f" [green]✓[/green] Created {en_path}") + + elif action_item.action == "update": + if not en_path.exists(): + console.print(" [yellow]⚠[/yellow] File not found, skipping update") + continue + + existing = en_path.read_text() + with console.status(f" [cyan]Updating {rel_path}..."): + content = _update_doc( + action_item.reason, + action_item.section or "", + existing, + diff, + client, + ) + + if not content: + console.print(" [yellow]⚠[/yellow] Empty response, skipping update") + continue + + if dry_run: + console.print(f" [dim][DRY RUN] Would update {en_path}[/dim]") + else: + en_path.write_text(content) + console.print(f" [green]✓[/green] Updated {en_path}") + + if not content: + continue + + resolved_docs = docs_dir.resolve() + for lang in _TRANSLATION_LANGS: + lang_path = (docs_dir / lang / rel_path).resolve() + if not lang_path.is_relative_to(resolved_docs): + continue + + with console.status(f" [cyan]Translating to {_LANGUAGE_NAMES[lang]}..."): + translated = _translate_doc(content, lang, client) + + if dry_run: + console.print(f" [dim][DRY RUN] Would write {lang_path}[/dim]") + else: + lang_path.parent.mkdir(parents=True, exist_ok=True) + lang_path.write_text(translated) + console.print(f" [green]✓[/green] Translated → {lang_path}") + + console.print("\n[green]✓ Done.[/green]") From b78ed655ea9720e45387cec84b0f4b012480a8da Mon Sep 17 00:00:00 2001 From: Greyson LaLonde Date: Wed, 25 Mar 2026 20:06:13 +0800 Subject: [PATCH 08/25] feat: bump versions to 1.12.0a1 --- lib/crewai-files/src/crewai_files/__init__.py | 2 +- lib/crewai-tools/pyproject.toml | 2 +- lib/crewai-tools/src/crewai_tools/__init__.py | 2 +- lib/crewai/pyproject.toml | 2 +- lib/crewai/src/crewai/__init__.py | 2 +- lib/crewai/src/crewai/cli/templates/crew/pyproject.toml | 2 +- lib/crewai/src/crewai/cli/templates/flow/pyproject.toml | 2 +- lib/crewai/src/crewai/cli/templates/tool/pyproject.toml | 2 +- lib/devtools/src/crewai_devtools/__init__.py | 2 +- 9 files changed, 9 insertions(+), 9 deletions(-) diff --git a/lib/crewai-files/src/crewai_files/__init__.py b/lib/crewai-files/src/crewai_files/__init__.py index 0d3544967..b2cc6f759 100644 --- a/lib/crewai-files/src/crewai_files/__init__.py +++ b/lib/crewai-files/src/crewai_files/__init__.py @@ -152,4 +152,4 @@ __all__ = [ "wrap_file_source", ] -__version__ = "1.11.1" +__version__ = "1.12.0a1" diff --git a/lib/crewai-tools/pyproject.toml b/lib/crewai-tools/pyproject.toml index d954818ee..abe95dd11 100644 --- a/lib/crewai-tools/pyproject.toml +++ b/lib/crewai-tools/pyproject.toml @@ -11,7 +11,7 @@ dependencies = [ "pytube~=15.0.0", "requests~=2.32.5", "docker~=7.1.0", - "crewai==1.11.1", + "crewai==1.12.0a1", "tiktoken~=0.8.0", "beautifulsoup4~=4.13.4", "python-docx~=1.2.0", diff --git a/lib/crewai-tools/src/crewai_tools/__init__.py b/lib/crewai-tools/src/crewai_tools/__init__.py index 5244cbfbd..aeb493b78 100644 --- a/lib/crewai-tools/src/crewai_tools/__init__.py +++ b/lib/crewai-tools/src/crewai_tools/__init__.py @@ -309,4 +309,4 @@ __all__ = [ "ZapierActionTools", ] -__version__ = "1.11.1" +__version__ = "1.12.0a1" diff --git a/lib/crewai/pyproject.toml b/lib/crewai/pyproject.toml index 8fc69adf6..0b52b26bc 100644 --- a/lib/crewai/pyproject.toml +++ b/lib/crewai/pyproject.toml @@ -54,7 +54,7 @@ Repository = "https://github.com/crewAIInc/crewAI" [project.optional-dependencies] tools = [ - "crewai-tools==1.11.1", + "crewai-tools==1.12.0a1", ] embeddings = [ "tiktoken~=0.8.0" diff --git a/lib/crewai/src/crewai/__init__.py b/lib/crewai/src/crewai/__init__.py index a4f4a0a1c..08fa2f98d 100644 --- a/lib/crewai/src/crewai/__init__.py +++ b/lib/crewai/src/crewai/__init__.py @@ -42,7 +42,7 @@ def _suppress_pydantic_deprecation_warnings() -> None: _suppress_pydantic_deprecation_warnings() -__version__ = "1.11.1" +__version__ = "1.12.0a1" _telemetry_submitted = False diff --git a/lib/crewai/src/crewai/cli/templates/crew/pyproject.toml b/lib/crewai/src/crewai/cli/templates/crew/pyproject.toml index 605b4eba5..2590a1c49 100644 --- a/lib/crewai/src/crewai/cli/templates/crew/pyproject.toml +++ b/lib/crewai/src/crewai/cli/templates/crew/pyproject.toml @@ -5,7 +5,7 @@ description = "{{name}} using crewAI" authors = [{ name = "Your Name", email = "you@example.com" }] requires-python = ">=3.10,<3.14" dependencies = [ - "crewai[tools]==1.11.1" + "crewai[tools]==1.12.0a1" ] [project.scripts] diff --git a/lib/crewai/src/crewai/cli/templates/flow/pyproject.toml b/lib/crewai/src/crewai/cli/templates/flow/pyproject.toml index 40a8cdf22..2f8eda95a 100644 --- a/lib/crewai/src/crewai/cli/templates/flow/pyproject.toml +++ b/lib/crewai/src/crewai/cli/templates/flow/pyproject.toml @@ -5,7 +5,7 @@ description = "{{name}} using crewAI" authors = [{ name = "Your Name", email = "you@example.com" }] requires-python = ">=3.10,<3.14" dependencies = [ - "crewai[tools]==1.11.1" + "crewai[tools]==1.12.0a1" ] [project.scripts] diff --git a/lib/crewai/src/crewai/cli/templates/tool/pyproject.toml b/lib/crewai/src/crewai/cli/templates/tool/pyproject.toml index 61b3bffd1..6aca3d7e4 100644 --- a/lib/crewai/src/crewai/cli/templates/tool/pyproject.toml +++ b/lib/crewai/src/crewai/cli/templates/tool/pyproject.toml @@ -5,7 +5,7 @@ description = "Power up your crews with {{folder_name}}" readme = "README.md" requires-python = ">=3.10,<3.14" dependencies = [ - "crewai[tools]==1.11.1" + "crewai[tools]==1.12.0a1" ] [tool.crewai] diff --git a/lib/devtools/src/crewai_devtools/__init__.py b/lib/devtools/src/crewai_devtools/__init__.py index 2b75f1f38..1df857042 100644 --- a/lib/devtools/src/crewai_devtools/__init__.py +++ b/lib/devtools/src/crewai_devtools/__init__.py @@ -1,3 +1,3 @@ """CrewAI development tools.""" -__version__ = "1.11.1" +__version__ = "1.12.0a1" From 74fb23aaa4ca68fc68f55d5177106243655b826f Mon Sep 17 00:00:00 2001 From: Greyson LaLonde Date: Wed, 25 Mar 2026 20:14:39 +0800 Subject: [PATCH 09/25] docs: update changelog and version for v1.12.0a1 --- docs/ar/changelog.mdx | 41 ++++++++++++++++++++++++++++++++++++++++ docs/en/changelog.mdx | 41 ++++++++++++++++++++++++++++++++++++++++ docs/ko/changelog.mdx | 41 ++++++++++++++++++++++++++++++++++++++++ docs/pt-BR/changelog.mdx | 41 ++++++++++++++++++++++++++++++++++++++++ 4 files changed, 164 insertions(+) diff --git a/docs/ar/changelog.mdx b/docs/ar/changelog.mdx index ad6311f77..6316b91a6 100644 --- a/docs/ar/changelog.mdx +++ b/docs/ar/changelog.mdx @@ -4,6 +4,47 @@ description: "تحديثات المنتج والتحسينات وإصلاحات icon: "clock" mode: "wide" --- + + ## 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 diff --git a/docs/en/changelog.mdx b/docs/en/changelog.mdx index a06001a4b..df519eb04 100644 --- a/docs/en/changelog.mdx +++ b/docs/en/changelog.mdx @@ -4,6 +4,47 @@ description: "Product updates, improvements, and bug fixes for CrewAI" icon: "clock" mode: "wide" --- + + ## v1.12.0a1 + + [View release on GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.12.0a1) + + ## What's Changed + + ### Features + - Add docs-check command to analyze changes and generate docs with translations + - Add Arabic language support to changelog and release tooling + - Add modern standard Arabic translation of all documentation + - Add native OpenAI-compatible providers (OpenRouter, DeepSeek, Ollama, vLLM, Cerebras, Dashscope) + - Add agent skills + - Add logout command in CLI + - Implement automatic root_scope for hierarchical memory isolation + + ### Bug Fixes + - Fix agent memory saving + - Resolve mypy errors in crewai-files and add all packages to CI type checks + - Resolve all strict mypy errors across crewai-tools package + - Resolve all mypy errors across crewai package + - Fix usage of __router_paths__ for listener+router methods in FlowMeta + - Pin litellm upper bound to last tested version (1.82.6) + - Raise value error on no file support + - Correct litellm quarantine wording in docs + + ### Documentation + - Add CONTRIBUTING.md + - Add guide for using CrewAI without LiteLLM + - Update changelog and version for v1.11.1 + + ### Refactoring + - Refactor to deduplicate sync/async task execution and kickoff in agent + - Decouple internal plumbing from litellm (token counting, callbacks, feature detection, errors) + + ## Contributors + + @alex-clawd, @greysonlalonde, @iris-clawd, @lorenzejay, @nicoferdi96 + + + ## v1.11.1 diff --git a/docs/ko/changelog.mdx b/docs/ko/changelog.mdx index ee293e339..03b8fc3cd 100644 --- a/docs/ko/changelog.mdx +++ b/docs/ko/changelog.mdx @@ -4,6 +4,47 @@ description: "CrewAI의 제품 업데이트, 개선 사항 및 버그 수정" icon: "clock" mode: "wide" --- + + ## v1.12.0a1 + + [GitHub 릴리스 보기](https://github.com/crewAIInc/crewAI/releases/tag/1.12.0a1) + + ## 변경 사항 + + ### 기능 + - 변경 사항을 분석하고 번역된 문서 생성하는 docs-check 명령 추가 + - 변경 로그 및 릴리스 도구에 아랍어 지원 추가 + - 모든 문서의 현대 표준 아랍어 번역 추가 + - OpenAI 호환 네이티브 제공업체 추가 (OpenRouter, DeepSeek, Ollama, vLLM, Cerebras, Dashscope) + - 에이전트 기술 추가 + - CLI에 로그아웃 명령 추가 + - 계층 메모리 격리를 위한 자동 root_scope 구현 + + ### 버그 수정 + - 에이전트 메모리 저장 문제 수정 + - crewai-files에서 mypy 오류 해결 및 모든 패키지를 CI 유형 검사에 추가 + - crewai-tools 패키지 전반에 걸쳐 모든 엄격한 mypy 오류 해결 + - crewai 패키지 전반에 걸쳐 모든 mypy 오류 해결 + - FlowMeta에서 listener+router 메서드의 __router_paths__ 사용 수정 + - litellm 상한을 마지막 테스트된 버전(1.82.6)으로 고정 + - 파일 지원이 없을 경우 값 오류 발생 + - 문서에서 litellm 격리 단어 수정 + + ### 문서 + - CONTRIBUTING.md 추가 + - LiteLLM 없이 CrewAI를 사용하는 가이드 추가 + - v1.11.1에 대한 변경 로그 및 버전 업데이트 + + ### 리팩토링 + - 에이전트에서 동기/비동기 작업 실행 및 시작을 중복 제거하도록 리팩토링 + - litellm과 내부 플러밍 분리 (토큰 수 세기, 콜백, 기능 감지, 오류) + + ## 기여자 + + @alex-clawd, @greysonlalonde, @iris-clawd, @lorenzejay, @nicoferdi96 + + + ## v1.11.1 diff --git a/docs/pt-BR/changelog.mdx b/docs/pt-BR/changelog.mdx index dc7df762e..4d5504e40 100644 --- a/docs/pt-BR/changelog.mdx +++ b/docs/pt-BR/changelog.mdx @@ -4,6 +4,47 @@ description: "Atualizações de produto, melhorias e correções do CrewAI" icon: "clock" mode: "wide" --- + + ## v1.12.0a1 + + [Ver release no GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.12.0a1) + + ## O que Mudou + + ### Funcionalidades + - Adicionar comando docs-check para analisar mudanças e gerar documentação com traduções + - Adicionar suporte ao idioma árabe para changelog e ferramentas de lançamento + - Adicionar tradução em árabe padrão moderno de toda a documentação + - Adicionar provedores compatíveis com OpenAI nativos (OpenRouter, DeepSeek, Ollama, vLLM, Cerebras, Dashscope) + - Adicionar habilidades de agente + - Adicionar comando de logout na CLI + - Implementar root_scope automático para isolamento de memória hierárquico + + ### Correções de Bugs + - Corrigir a economia de memória do agente + - Resolver erros do mypy em crewai-files e adicionar todos os pacotes às verificações de tipo do CI + - Resolver todos os erros estritos do mypy no pacote crewai-tools + - Resolver todos os erros do mypy no pacote crewai + - Corrigir o uso de __router_paths__ para métodos listener+router em FlowMeta + - Fixar o limite superior do litellm na última versão testada (1.82.6) + - Levantar erro de valor quando não houver suporte a arquivos + - Corrigir a redação da quarentena do litellm na documentação + + ### Documentação + - Adicionar CONTRIBUTING.md + - Adicionar guia para usar o CrewAI sem o LiteLLM + - Atualizar changelog e versão para v1.11.1 + + ### Refatoração + - Refatorar para deduplicar a execução de tarefas síncronas/assíncronas e o início no agente + - Desacoplar a estrutura interna do litellm (contagem de tokens, callbacks, detecção de recursos, erros) + + ## Contribuidores + + @alex-clawd, @greysonlalonde, @iris-clawd, @lorenzejay, @nicoferdi96 + + + ## v1.11.1 From 90caa621580c08d84630c6b0c554b3b85c991cfc Mon Sep 17 00:00:00 2001 From: Greyson LaLonde Date: Wed, 25 Mar 2026 20:55:03 +0800 Subject: [PATCH 10/25] chore: run ruff check and format on all files in CI --- .github/workflows/linter.yml | 27 ++----------- lib/crewai/src/crewai/memory/memory_scope.py | 42 ++++++++++---------- 2 files changed, 25 insertions(+), 44 deletions(-) diff --git a/.github/workflows/linter.yml b/.github/workflows/linter.yml index ae26c4209..ecef1d1f6 100644 --- a/.github/workflows/linter.yml +++ b/.github/workflows/linter.yml @@ -8,15 +8,8 @@ permissions: jobs: lint: runs-on: ubuntu-latest - env: - TARGET_BRANCH: ${{ github.event.pull_request.base.ref }} steps: - uses: actions/checkout@v4 - with: - fetch-depth: 0 - - - name: Fetch Target Branch - run: git fetch origin $TARGET_BRANCH --depth=1 - name: Restore global uv cache id: cache-restore @@ -40,23 +33,11 @@ jobs: - 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' diff --git a/lib/crewai/src/crewai/memory/memory_scope.py b/lib/crewai/src/crewai/memory/memory_scope.py index 2384600f4..de074ce25 100644 --- a/lib/crewai/src/crewai/memory/memory_scope.py +++ b/lib/crewai/src/crewai/memory/memory_scope.py @@ -80,28 +80,28 @@ class MemoryScope(BaseModel): ) def remember_many( - self, - contents: list[str], - scope: str | None = "/", - categories: list[str] | None = None, - metadata: dict[str, Any] | None = None, - importance: float | None = None, - source: str | None = None, - private: bool = False, - agent_role: str | None = None, + self, + contents: list[str], + scope: str | None = "/", + categories: list[str] | None = None, + metadata: dict[str, Any] | None = None, + importance: float | None = None, + source: str | None = None, + private: bool = False, + agent_role: str | None = None, ) -> list[MemoryRecord]: - """Remember multiple items; scope is relative to this scope's root.""" - path = self._scope_path(scope) - return self._memory.remember_many( - contents, - scope=path, - categories=categories, - metadata=metadata, - importance=importance, - source=source, - private=private, - agent_role=agent_role, - ) + """Remember multiple items; scope is relative to this scope's root.""" + path = self._scope_path(scope) + return self._memory.remember_many( + contents, + scope=path, + categories=categories, + metadata=metadata, + importance=importance, + source=source, + private=private, + agent_role=agent_role, + ) def recall( self, From 1cc251b4b8d2ddb9523210219d9454d3f476a9ab Mon Sep 17 00:00:00 2001 From: Greyson LaLonde Date: Wed, 25 Mar 2026 23:42:09 +0800 Subject: [PATCH 11/25] feat: add Qdrant Edge storage backend for memory system --- lib/crewai/pyproject.toml | 3 + .../memory/storage/qdrant_edge_storage.py | 872 ++++++++++++++++++ .../src/crewai/memory/unified_memory.py | 21 +- .../tests/memory/test_qdrant_edge_storage.py | 353 +++++++ uv.lock | 27 +- 5 files changed, 1268 insertions(+), 8 deletions(-) create mode 100644 lib/crewai/src/crewai/memory/storage/qdrant_edge_storage.py create mode 100644 lib/crewai/tests/memory/test_qdrant_edge_storage.py diff --git a/lib/crewai/pyproject.toml b/lib/crewai/pyproject.toml index 0b52b26bc..2a80698b5 100644 --- a/lib/crewai/pyproject.toml +++ b/lib/crewai/pyproject.toml @@ -106,6 +106,9 @@ a2a = [ file-processing = [ "crewai-files", ] +qdrant-edge = [ + "qdrant-edge-py>=0.6.0", +] [project.scripts] diff --git a/lib/crewai/src/crewai/memory/storage/qdrant_edge_storage.py b/lib/crewai/src/crewai/memory/storage/qdrant_edge_storage.py new file mode 100644 index 000000000..f20faa408 --- /dev/null +++ b/lib/crewai/src/crewai/memory/storage/qdrant_edge_storage.py @@ -0,0 +1,872 @@ +"""Qdrant Edge storage backend for the unified memory system. + +Uses a write-local/sync-central pattern for safe multi-process access. +Each worker process writes to its own local shard (keyed by PID). Reads +fan out to both local and central shards, merging results. On close, +local records are flushed to the shared central shard. +""" + +from __future__ import annotations + +import asyncio +import atexit +from datetime import datetime, timezone +import logging +import os +from pathlib import Path +import shutil +from typing import Any, Final +import uuid + +from qdrant_edge import ( + CountRequest, + Distance, + EdgeConfig, + EdgeShard, + EdgeVectorParams, + FacetRequest, + FieldCondition, + Filter, + MatchValue, + PayloadSchemaType, + Point, + Query, + QueryRequest, + ScrollRequest, + UpdateOperation, +) + +from crewai.memory.types import MemoryRecord, ScopeInfo + + +_logger = logging.getLogger(__name__) + +VECTOR_NAME: Final[str] = "memory" + +DEFAULT_VECTOR_DIM: Final[int] = 1536 + +_SCROLL_BATCH: Final[int] = 256 + + +def _uuid_to_point_id(uuid_str: str) -> int: + """Convert a UUID string to a stable Qdrant point ID. + + Falls back to hashing for non-UUID strings. + """ + try: + return uuid.UUID(uuid_str).int % (2**63 - 1) + except ValueError: + return int.from_bytes(uuid_str.encode()[:8].ljust(8, b"\x00"), "big") % ( + 2**63 - 1 + ) + + +def _build_scope_ancestors(scope: str) -> list[str]: + """Build the list of all ancestor scopes for prefix filtering. + + For scope ``/crew/sales/agent``, returns + ``["/", "/crew", "/crew/sales", "/crew/sales/agent"]``. + """ + parts = scope.strip("/").split("/") + ancestors: list[str] = ["/"] + current = "" + for part in parts: + if part: + current = f"{current}/{part}" + ancestors.append(current) + return ancestors + + +class QdrantEdgeStorage: + """Qdrant Edge storage backend with write-local/sync-central pattern. + + Each worker process gets its own local shard for writes. + Reads merge results from both local and central shards. On close, + local records are flushed to the shared central shard. + """ + + def __init__( + self, + path: str | Path | None = None, + vector_dim: int | None = None, + ) -> None: + """Initialize Qdrant Edge storage. + + Args: + path: Base directory for shard storage. Defaults to + ``$CREWAI_STORAGE_DIR/memory/qdrant-edge`` or the + platform data directory. + vector_dim: Embedding vector dimensionality. Auto-detected + from the first saved embedding when ``None``. + """ + if path is None: + storage_dir = os.environ.get("CREWAI_STORAGE_DIR") + if storage_dir: + path = Path(storage_dir) / "memory" / "qdrant-edge" + else: + from crewai.utilities.paths import db_storage_path + + path = Path(db_storage_path()) / "memory" / "qdrant-edge" + + self._base_path = Path(path) + self._central_path = self._base_path / "central" + self._local_path = self._base_path / f"worker-{os.getpid()}" + self._vector_dim = vector_dim or 0 + self._config: EdgeConfig | None = None + self._local_has_data = self._local_path.exists() + self._closed = False + self._indexes_created = False + + if self._vector_dim > 0: + self._config = self._build_config(self._vector_dim) + + if self._config is None and self._central_path.exists(): + try: + shard = EdgeShard.load(str(self._central_path)) + if shard.count(CountRequest()) > 0: + pts, _ = shard.scroll( + ScrollRequest(limit=1, with_payload=False, with_vector=True) + ) + if pts and pts[0].vector: + vec = pts[0].vector + if isinstance(vec, dict) and VECTOR_NAME in vec: + vec_data = vec[VECTOR_NAME] + dim = len(vec_data) if isinstance(vec_data, list) else 0 + if dim > 0: + self._vector_dim = dim + self._config = self._build_config(dim) + shard.close() + except Exception: + _logger.debug("Failed to detect dim from central shard", exc_info=True) + + self._cleanup_orphaned_shards() + atexit.register(self.close) + + @staticmethod + def _build_config(dim: int) -> EdgeConfig: + """Build an EdgeConfig for the given vector dimensionality.""" + return EdgeConfig( + vectors={VECTOR_NAME: EdgeVectorParams(size=dim, distance=Distance.Cosine)}, + ) + + def _open_shard(self, path: Path) -> EdgeShard: + """Open an existing shard or create a new one at *path*.""" + path.mkdir(parents=True, exist_ok=True) + try: + return EdgeShard.load(str(path)) + except Exception: + if self._config is None: + raise + return EdgeShard.create(str(path), self._config) + + def _ensure_indexes(self, shard: EdgeShard) -> None: + """Create payload indexes for efficient filtering.""" + if self._indexes_created: + return + try: + shard.update( + UpdateOperation.create_field_index( + "scope_ancestors", PayloadSchemaType.Keyword + ) + ) + shard.update( + UpdateOperation.create_field_index( + "categories", PayloadSchemaType.Keyword + ) + ) + shard.update( + UpdateOperation.create_field_index( + "record_id", PayloadSchemaType.Keyword + ) + ) + self._indexes_created = True + except Exception: + _logger.debug("Index creation failed (may already exist)", exc_info=True) + + def _record_to_point(self, record: MemoryRecord) -> Point: + """Convert a MemoryRecord to a Qdrant Point.""" + return Point( + id=_uuid_to_point_id(record.id), + vector={ + VECTOR_NAME: record.embedding + if record.embedding + else [0.0] * self._vector_dim, + }, + payload={ + "record_id": record.id, + "content": record.content, + "scope": record.scope, + "scope_ancestors": _build_scope_ancestors(record.scope), + "categories": record.categories, + "metadata": record.metadata, + "importance": record.importance, + "created_at": record.created_at.isoformat(), + "last_accessed": record.last_accessed.isoformat(), + "source": record.source or "", + "private": record.private, + }, + ) + + @staticmethod + def _payload_to_record( + payload: dict[str, Any], + vector: dict[str, list[float]] | None = None, + ) -> MemoryRecord: + """Reconstruct a MemoryRecord from a Qdrant payload.""" + + def _parse_dt(val: Any) -> datetime: + if val is None: + return datetime.now(timezone.utc).replace(tzinfo=None) + if isinstance(val, datetime): + return val + return datetime.fromisoformat(str(val).replace("Z", "+00:00")) + + return MemoryRecord( + id=str(payload["record_id"]), + content=str(payload["content"]), + scope=str(payload["scope"]), + categories=payload.get("categories", []), + metadata=payload.get("metadata", {}), + importance=float(payload.get("importance", 0.5)), + created_at=_parse_dt(payload.get("created_at")), + last_accessed=_parse_dt(payload.get("last_accessed")), + embedding=vector.get(VECTOR_NAME) if vector else None, + source=payload.get("source") or None, + private=bool(payload.get("private", False)), + ) + + @staticmethod + def _build_scope_filter(scope_prefix: str | None) -> Filter | None: + """Build a Qdrant Filter for scope prefix matching.""" + if scope_prefix is None or not scope_prefix.strip("/"): + return None + prefix = scope_prefix.rstrip("/") + if not prefix.startswith("/"): + prefix = "/" + prefix + return Filter( + must=[FieldCondition(key="scope_ancestors", match=MatchValue(value=prefix))] + ) + + @staticmethod + def _scroll_all( + shard: EdgeShard, + filt: Filter | None = None, + with_vector: bool = False, + ) -> list[Any]: + """Scroll all points matching a filter from a shard.""" + all_points: list[Any] = [] + offset = None + while True: + batch, next_offset = shard.scroll( + ScrollRequest( + limit=_SCROLL_BATCH, + offset=offset, + with_payload=True, + with_vector=with_vector, + filter=filt, + ) + ) + all_points.extend(batch) + if next_offset is None or not batch: + break + offset = next_offset + return all_points + + def save(self, records: list[MemoryRecord]) -> None: + """Save records to the worker-local shard.""" + if not records: + return + + if self._vector_dim == 0: + for r in records: + if r.embedding and len(r.embedding) > 0: + self._vector_dim = len(r.embedding) + break + if self._config is None and self._vector_dim > 0: + self._config = self._build_config(self._vector_dim) + if self._config is None: + self._config = self._build_config(DEFAULT_VECTOR_DIM) + self._vector_dim = DEFAULT_VECTOR_DIM + + points = [self._record_to_point(r) for r in records] + local = self._open_shard(self._local_path) + try: + self._ensure_indexes(local) + local.update(UpdateOperation.upsert_points(points)) + local.flush() + self._local_has_data = True + finally: + local.close() + + def search( + self, + query_embedding: list[float], + scope_prefix: str | None = None, + categories: list[str] | None = None, + metadata_filter: dict[str, Any] | None = None, + limit: int = 10, + min_score: float = 0.0, + ) -> list[tuple[MemoryRecord, float]]: + """Search both central and local shards, merge results.""" + filt = self._build_scope_filter(scope_prefix) + fetch_limit = limit * 3 if (categories or metadata_filter) else limit + all_scored: list[tuple[dict[str, Any], float, bool]] = [] + + for shard_path in (self._central_path, self._local_path): + if not shard_path.exists(): + continue + is_local = shard_path == self._local_path + try: + shard = EdgeShard.load(str(shard_path)) + results = shard.query( + QueryRequest( + query=Query.Nearest(list(query_embedding), using=VECTOR_NAME), + filter=filt, + limit=fetch_limit, + with_payload=True, + with_vector=False, + ) + ) + all_scored.extend( + (sp.payload or {}, float(sp.score), is_local) for sp in results + ) + shard.close() + except Exception: + _logger.debug("Search failed on %s", shard_path, exc_info=True) + + seen: dict[str, tuple[dict[str, Any], float]] = {} + local_ids: set[str] = set() + for payload, score, is_local in all_scored: + rid = payload["record_id"] + if is_local: + local_ids.add(rid) + seen[rid] = (payload, score) + elif rid not in local_ids: + if rid not in seen or score > seen[rid][1]: + seen[rid] = (payload, score) + + ranked = sorted(seen.values(), key=lambda x: x[1], reverse=True) + out: list[tuple[MemoryRecord, float]] = [] + for payload, score in ranked: + record = self._payload_to_record(payload) + if categories and not any(c in record.categories for c in categories): + continue + if metadata_filter and not all( + record.metadata.get(k) == v for k, v in metadata_filter.items() + ): + continue + if score < min_score: + continue + out.append((record, score)) + if len(out) >= limit: + break + return out[:limit] + + def delete( + self, + scope_prefix: str | None = None, + categories: list[str] | None = None, + record_ids: list[str] | None = None, + older_than: datetime | None = None, + metadata_filter: dict[str, Any] | None = None, + ) -> int: + """Delete matching records from central shard.""" + total_deleted = 0 + for shard_path in (self._central_path, self._local_path): + if not shard_path.exists(): + continue + try: + total_deleted += self._delete_from_shard_path( + shard_path, + scope_prefix, + categories, + record_ids, + older_than, + metadata_filter, + ) + except Exception: + _logger.debug("Delete failed on %s", shard_path, exc_info=True) + return total_deleted + + def _delete_from_shard_path( + self, + shard_path: Path, + scope_prefix: str | None, + categories: list[str] | None, + record_ids: list[str] | None, + older_than: datetime | None, + metadata_filter: dict[str, Any] | None, + ) -> int: + """Delete matching records from a shard at the given path.""" + shard = EdgeShard.load(str(shard_path)) + try: + deleted = self._delete_from_shard( + shard, + scope_prefix, + categories, + record_ids, + older_than, + metadata_filter, + ) + shard.flush() + finally: + shard.close() + return deleted + + def _delete_from_shard( + self, + shard: EdgeShard, + scope_prefix: str | None, + categories: list[str] | None, + record_ids: list[str] | None, + older_than: datetime | None, + metadata_filter: dict[str, Any] | None, + ) -> int: + """Delete matching records from a single shard, returning count deleted.""" + before = shard.count(CountRequest()) + + if record_ids and not (categories or metadata_filter or older_than): + point_ids: list[int | uuid.UUID | str] = [ + _uuid_to_point_id(rid) for rid in record_ids + ] + shard.update(UpdateOperation.delete_points(point_ids)) + return before - shard.count(CountRequest()) + + if categories or metadata_filter or older_than: + scope_filter = self._build_scope_filter(scope_prefix) + points = self._scroll_all(shard, filt=scope_filter) + allowed_ids: set[str] | None = set(record_ids) if record_ids else None + to_delete: list[int | uuid.UUID | str] = [] + for pt in points: + record = self._payload_to_record(pt.payload or {}) + if allowed_ids and record.id not in allowed_ids: + continue + if categories and not any(c in record.categories for c in categories): + continue + if metadata_filter and not all( + record.metadata.get(k) == v for k, v in metadata_filter.items() + ): + continue + if older_than and record.created_at >= older_than: + continue + to_delete.append(pt.id) + if to_delete: + shard.update(UpdateOperation.delete_points(to_delete)) + return before - shard.count(CountRequest()) + + scope_filter = self._build_scope_filter(scope_prefix) + if scope_filter: + shard.update(UpdateOperation.delete_points_by_filter(filter=scope_filter)) + else: + points = self._scroll_all(shard) + if points: + all_ids: list[int | uuid.UUID | str] = [p.id for p in points] + shard.update(UpdateOperation.delete_points(all_ids)) + return before - shard.count(CountRequest()) + + def update(self, record: MemoryRecord) -> None: + """Update a record by upserting with the same point ID.""" + if self._config is None: + if record.embedding and len(record.embedding) > 0: + self._vector_dim = len(record.embedding) + self._config = self._build_config(self._vector_dim) + else: + self._config = self._build_config(DEFAULT_VECTOR_DIM) + self._vector_dim = DEFAULT_VECTOR_DIM + + point = self._record_to_point(record) + local = self._open_shard(self._local_path) + try: + self._ensure_indexes(local) + local.update(UpdateOperation.upsert_points([point])) + local.flush() + self._local_has_data = True + finally: + local.close() + + def get_record(self, record_id: str) -> MemoryRecord | None: + """Return a single record by ID, or None if not found.""" + point_id = _uuid_to_point_id(record_id) + for shard_path in (self._local_path, self._central_path): + if not shard_path.exists(): + continue + try: + shard = EdgeShard.load(str(shard_path)) + records = shard.retrieve([point_id], True, True) + shard.close() + if records: + payload = records[0].payload or {} + vec = records[0].vector + vec_dict = vec if isinstance(vec, dict) else None + return self._payload_to_record(payload, vec_dict) # type: ignore[arg-type] + except Exception: + _logger.debug("get_record failed on %s", shard_path, exc_info=True) + return None + + def list_records( + self, + scope_prefix: str | None = None, + limit: int = 200, + offset: int = 0, + ) -> list[MemoryRecord]: + """List records in a scope, newest first.""" + filt = self._build_scope_filter(scope_prefix) + all_records: list[MemoryRecord] = [] + seen_ids: set[str] = set() + + for shard_path in (self._local_path, self._central_path): + if not shard_path.exists(): + continue + try: + shard = EdgeShard.load(str(shard_path)) + points = self._scroll_all(shard, filt=filt) + shard.close() + for pt in points: + rid = pt.payload["record_id"] + if rid not in seen_ids: + seen_ids.add(rid) + all_records.append(self._payload_to_record(pt.payload)) + except Exception: + _logger.debug("list_records failed on %s", shard_path, exc_info=True) + + all_records.sort(key=lambda r: r.created_at, reverse=True) + return all_records[offset : offset + limit] + + def get_scope_info(self, scope: str) -> ScopeInfo: + """Get information about a scope.""" + scope = scope.rstrip("/") or "/" + prefix = scope if scope != "/" else None + filt = self._build_scope_filter(prefix) + + all_points: list[Any] = [] + for shard_path in (self._central_path, self._local_path): + if not shard_path.exists(): + continue + try: + shard = EdgeShard.load(str(shard_path)) + all_points.extend(self._scroll_all(shard, filt=filt)) + shard.close() + except Exception: + _logger.debug("get_scope_info failed on %s", shard_path, exc_info=True) + + if not all_points: + return ScopeInfo( + path=scope, + record_count=0, + categories=[], + oldest_record=None, + newest_record=None, + child_scopes=[], + ) + + seen: dict[str, Any] = {} + for pt in all_points: + rid = pt.payload["record_id"] + if rid not in seen: + seen[rid] = pt + + categories_set: set[str] = set() + oldest: datetime | None = None + newest: datetime | None = None + child_prefix = (scope + "/") if scope != "/" else "/" + children: set[str] = set() + + for pt in seen.values(): + payload = pt.payload + sc = str(payload.get("scope", "")) + if child_prefix and sc.startswith(child_prefix): + rest = sc[len(child_prefix) :] + first_component = rest.split("/", 1)[0] + if first_component: + children.add(child_prefix + first_component) + for c in payload.get("categories", []): + categories_set.add(c) + created = payload.get("created_at") + if created: + dt = datetime.fromisoformat(str(created).replace("Z", "+00:00")) + if oldest is None or dt < oldest: + oldest = dt + if newest is None or dt > newest: + newest = dt + + return ScopeInfo( + path=scope, + record_count=len(seen), + categories=sorted(categories_set), + oldest_record=oldest, + newest_record=newest, + child_scopes=sorted(children), + ) + + def list_scopes(self, parent: str = "/") -> list[str]: + """List immediate child scopes under a parent path.""" + parent = parent.rstrip("/") or "" + prefix = (parent + "/") if parent else "/" + + all_scopes: set[str] = set() + filt = self._build_scope_filter(prefix if prefix != "/" else None) + for shard_path in (self._central_path, self._local_path): + if not shard_path.exists(): + continue + try: + shard = EdgeShard.load(str(shard_path)) + points = self._scroll_all(shard, filt=filt) + shard.close() + for pt in points: + sc = str(pt.payload.get("scope", "")) + if sc.startswith(prefix) and sc != (prefix.rstrip("/") or "/"): + rest = sc[len(prefix) :] + first_component = rest.split("/", 1)[0] + if first_component: + all_scopes.add(prefix + first_component) + except Exception: + _logger.debug("list_scopes failed on %s", shard_path, exc_info=True) + return sorted(all_scopes) + + def list_categories(self, scope_prefix: str | None = None) -> dict[str, int]: + """List categories and their counts within a scope.""" + if not self._local_has_data and self._central_path.exists(): + try: + shard = EdgeShard.load(str(self._central_path)) + try: + shard.update( + UpdateOperation.create_field_index( + "categories", PayloadSchemaType.Keyword + ) + ) + except Exception: # noqa: S110 + pass + filt = self._build_scope_filter(scope_prefix) + facet_result = shard.facet( + FacetRequest(key="categories", limit=1000, filter=filt) + ) + shard.close() + return {str(hit.value): hit.count for hit in facet_result.hits} + except Exception: + _logger.debug("list_categories failed on central", exc_info=True) + + counts: dict[str, int] = {} + for record in self.list_records(scope_prefix=scope_prefix, limit=50_000): + for c in record.categories: + counts[c] = counts.get(c, 0) + 1 + return counts + + def count(self, scope_prefix: str | None = None) -> int: + """Count records in scope (and subscopes).""" + filt = self._build_scope_filter(scope_prefix) + if not self._local_has_data: + if self._central_path.exists(): + try: + shard = EdgeShard.load(str(self._central_path)) + result = shard.count(CountRequest(filter=filt)) + shard.close() + return result + except Exception: + _logger.debug("count failed on central", exc_info=True) + return 0 + seen_ids: set[str] = set() + for shard_path in (self._local_path, self._central_path): + if not shard_path.exists(): + continue + try: + shard = EdgeShard.load(str(shard_path)) + for pt in self._scroll_all(shard, filt=filt): + seen_ids.add(pt.payload["record_id"]) + shard.close() + except Exception: + _logger.debug("count failed on %s", shard_path, exc_info=True) + return len(seen_ids) + + def reset(self, scope_prefix: str | None = None) -> None: + """Reset (delete all) memories in scope.""" + if scope_prefix is None or not scope_prefix.strip("/"): + for shard_path in (self._central_path, self._local_path): + if shard_path.exists(): + shutil.rmtree(shard_path, ignore_errors=True) + self._local_has_data = False + self._indexes_created = False + return + + self.delete(scope_prefix=scope_prefix) + + def touch_records(self, record_ids: list[str]) -> None: + """Update last_accessed to now for the given record IDs.""" + if not record_ids: + return + now = datetime.now(timezone.utc).replace(tzinfo=None).isoformat() + point_ids: list[int | uuid.UUID | str] = [ + _uuid_to_point_id(rid) for rid in record_ids + ] + for shard_path in (self._central_path, self._local_path): + if not shard_path.exists(): + continue + try: + shard = EdgeShard.load(str(shard_path)) + shard.update( + UpdateOperation.set_payload(point_ids, {"last_accessed": now}) + ) + shard.flush() + shard.close() + except Exception: + _logger.debug("touch_records failed on %s", shard_path, exc_info=True) + + def optimize(self) -> None: + """Compact the central shard synchronously.""" + if not self._central_path.exists(): + return + try: + shard = EdgeShard.load(str(self._central_path)) + shard.optimize() + shard.close() + except Exception: + _logger.debug("optimize failed", exc_info=True) + + def _upsert_to_central(self, points: list[Any]) -> None: + """Convert scrolled points to Qdrant Points and upsert to central shard.""" + qdrant_points = [ + Point( + id=pt.id, + vector=pt.vector if pt.vector else {}, + payload=pt.payload if pt.payload else {}, + ) + for pt in points + ] + central = self._open_shard(self._central_path) + try: + self._ensure_indexes(central) + central.update(UpdateOperation.upsert_points(qdrant_points)) + central.flush() + finally: + central.close() + + def flush_to_central(self) -> None: + """Sync local shard records to the central shard.""" + if not self._local_has_data or not self._local_path.exists(): + return + + try: + local = EdgeShard.load(str(self._local_path)) + except Exception: + _logger.debug("flush_to_central: failed to open local shard", exc_info=True) + return + + points = self._scroll_all(local, with_vector=True) + local.close() + + if not points: + shutil.rmtree(self._local_path, ignore_errors=True) + self._local_has_data = False + return + + self._upsert_to_central(points) + shutil.rmtree(self._local_path, ignore_errors=True) + self._local_has_data = False + + def close(self) -> None: + """Flush local shard to central and clean up.""" + if self._closed: + return + self._closed = True + atexit.unregister(self.close) + try: + self.flush_to_central() + except Exception: + _logger.debug("close: flush_to_central failed", exc_info=True) + + def _cleanup_orphaned_shards(self) -> None: + """Sync and remove local shards from dead worker processes.""" + if not self._base_path.exists(): + return + for entry in self._base_path.iterdir(): + if not entry.is_dir() or not entry.name.startswith("worker-"): + continue + pid_str = entry.name.removeprefix("worker-") + try: + pid = int(pid_str) + except ValueError: + continue + if pid == os.getpid(): + continue + try: + os.kill(pid, 0) + continue + except ProcessLookupError: + _logger.debug("Worker %d is dead, shard is orphaned", pid) + except PermissionError: + continue + + _logger.info("Cleaning up orphaned shard for dead worker %d", pid) + try: + orphan = EdgeShard.load(str(entry)) + points = self._scroll_all(orphan, with_vector=True) + orphan.close() + + if not points: + shutil.rmtree(entry, ignore_errors=True) + continue + + if self._config is None: + for pt in points: + vec = pt.vector + if isinstance(vec, dict) and VECTOR_NAME in vec: + vec_data = vec[VECTOR_NAME] + if isinstance(vec_data, list) and len(vec_data) > 0: + self._vector_dim = len(vec_data) + self._config = self._build_config(self._vector_dim) + break + + if self._config is None: + _logger.warning( + "Cannot recover orphaned shard %s: vector dimension unknown", + entry, + ) + continue + + self._upsert_to_central(points) + shutil.rmtree(entry, ignore_errors=True) + except Exception: + _logger.warning( + "Failed to recover orphaned shard %s", entry, exc_info=True + ) + + async def asave(self, records: list[MemoryRecord]) -> None: + """Save memory records asynchronously.""" + await asyncio.to_thread(self.save, records) + + async def asearch( + self, + query_embedding: list[float], + scope_prefix: str | None = None, + categories: list[str] | None = None, + metadata_filter: dict[str, Any] | None = None, + limit: int = 10, + min_score: float = 0.0, + ) -> list[tuple[MemoryRecord, float]]: + """Search for memories asynchronously.""" + return await asyncio.to_thread( + self.search, + query_embedding, + scope_prefix=scope_prefix, + categories=categories, + metadata_filter=metadata_filter, + limit=limit, + min_score=min_score, + ) + + async def adelete( + self, + scope_prefix: str | None = None, + categories: list[str] | None = None, + record_ids: list[str] | None = None, + older_than: datetime | None = None, + metadata_filter: dict[str, Any] | None = None, + ) -> int: + """Delete memories asynchronously.""" + return await asyncio.to_thread( + self.delete, + scope_prefix=scope_prefix, + categories=categories, + record_ids=record_ids, + older_than=older_than, + metadata_filter=metadata_filter, + ) diff --git a/lib/crewai/src/crewai/memory/unified_memory.py b/lib/crewai/src/crewai/memory/unified_memory.py index 488e3c94a..1454f0fcf 100644 --- a/lib/crewai/src/crewai/memory/unified_memory.py +++ b/lib/crewai/src/crewai/memory/unified_memory.py @@ -173,13 +173,18 @@ class Memory(BaseModel): ) if isinstance(self.storage, str): - from crewai.memory.storage.lancedb_storage import LanceDBStorage + if self.storage == "qdrant-edge": + from crewai.memory.storage.qdrant_edge_storage import QdrantEdgeStorage - self._storage = ( - LanceDBStorage() - if self.storage == "lancedb" - else LanceDBStorage(path=self.storage) - ) + self._storage = QdrantEdgeStorage() + elif self.storage == "lancedb": + from crewai.memory.storage.lancedb_storage import LanceDBStorage + + self._storage = LanceDBStorage() + else: + from crewai.memory.storage.lancedb_storage import LanceDBStorage + + self._storage = LanceDBStorage(path=self.storage) else: self._storage = self.storage @@ -293,8 +298,10 @@ class Memory(BaseModel): future.result() # blocks until done; re-raises exceptions def close(self) -> None: - """Drain pending saves and shut down the background thread pool.""" + """Drain pending saves, flush storage, and shut down the background thread pool.""" self.drain_writes() + if hasattr(self._storage, "close"): + self._storage.close() self._save_pool.shutdown(wait=True) def _encode_batch( diff --git a/lib/crewai/tests/memory/test_qdrant_edge_storage.py b/lib/crewai/tests/memory/test_qdrant_edge_storage.py new file mode 100644 index 000000000..a5b36c0a2 --- /dev/null +++ b/lib/crewai/tests/memory/test_qdrant_edge_storage.py @@ -0,0 +1,353 @@ +"""Tests for Qdrant Edge storage backend.""" + +from __future__ import annotations + +import importlib +from datetime import datetime, timedelta, timezone +from pathlib import Path +from typing import TYPE_CHECKING, Any +from unittest.mock import MagicMock + +import pytest + +pytestmark = pytest.mark.skipif( + importlib.util.find_spec("qdrant_edge") is None, + reason="qdrant-edge-py not installed", +) + +if TYPE_CHECKING: + from crewai.memory.storage.qdrant_edge_storage import QdrantEdgeStorage + +from crewai.memory.types import MemoryRecord + + +def _make_storage(path: str, vector_dim: int = 4) -> QdrantEdgeStorage: + from crewai.memory.storage.qdrant_edge_storage import QdrantEdgeStorage + + return QdrantEdgeStorage(path=path, vector_dim=vector_dim) + + +@pytest.fixture +def storage(tmp_path: Path) -> QdrantEdgeStorage: + return _make_storage(str(tmp_path / "edge")) + + +def _rec( + content: str = "test", + scope: str = "/", + categories: list[str] | None = None, + importance: float = 0.5, + embedding: list[float] | None = None, + metadata: dict | None = None, + created_at: datetime | None = None, +) -> MemoryRecord: + return MemoryRecord( + content=content, + scope=scope, + categories=categories or [], + importance=importance, + embedding=embedding or [0.1, 0.2, 0.3, 0.4], + metadata=metadata or {}, + **({"created_at": created_at} if created_at else {}), + ) + + +# --- Basic CRUD --- + + +def test_save_search(storage: QdrantEdgeStorage) -> None: + r = _rec(content="test content", scope="/foo", categories=["cat1"], importance=0.8) + storage.save([r]) + results = storage.search([0.1, 0.2, 0.3, 0.4], scope_prefix="/foo", limit=5) + assert len(results) == 1 + rec, score = results[0] + assert rec.content == "test content" + assert rec.scope == "/foo" + assert score >= 0.0 + + +def test_delete_count(storage: QdrantEdgeStorage) -> None: + r = _rec(scope="/") + storage.save([r]) + assert storage.count() == 1 + n = storage.delete(scope_prefix="/") + assert n >= 1 + assert storage.count() == 0 + + +def test_update_get_record(storage: QdrantEdgeStorage) -> None: + r = _rec(content="original", scope="/a") + storage.save([r]) + r.content = "updated" + storage.update(r) + found = storage.get_record(r.id) + assert found is not None + assert found.content == "updated" + + +def test_get_record_not_found(storage: QdrantEdgeStorage) -> None: + assert storage.get_record("nonexistent-id") is None + + +# --- Scope operations --- + + +def test_list_scopes_get_scope_info(storage: QdrantEdgeStorage) -> None: + storage.save([ + _rec(content="a", scope="/"), + _rec(content="b", scope="/team"), + ]) + scopes = storage.list_scopes("/") + assert "/team" in scopes + info = storage.get_scope_info("/") + assert info.record_count >= 1 + assert info.path == "/" + + +def test_scope_prefix_filter(storage: QdrantEdgeStorage) -> None: + storage.save([ + _rec(content="sales note", scope="/crew/sales"), + _rec(content="eng note", scope="/crew/eng"), + _rec(content="other note", scope="/other"), + ]) + results = storage.search([0.1, 0.2, 0.3, 0.4], scope_prefix="/crew", limit=10) + assert len(results) == 2 + scopes = {r.scope for r, _ in results} + assert "/crew/sales" in scopes + assert "/crew/eng" in scopes + + +# --- Filtering --- + + +def test_category_filter(storage: QdrantEdgeStorage) -> None: + storage.save([ + _rec(content="cat1 item", categories=["cat1"]), + _rec(content="cat2 item", categories=["cat2"]), + ]) + results = storage.search( + [0.1, 0.2, 0.3, 0.4], categories=["cat1"], limit=10 + ) + assert len(results) == 1 + assert results[0][0].categories == ["cat1"] + + +def test_metadata_filter(storage: QdrantEdgeStorage) -> None: + storage.save([ + _rec(content="with key", metadata={"env": "prod"}), + _rec(content="without key", metadata={"env": "dev"}), + ]) + results = storage.search( + [0.1, 0.2, 0.3, 0.4], metadata_filter={"env": "prod"}, limit=10 + ) + assert len(results) == 1 + assert results[0][0].metadata["env"] == "prod" + + +# --- List & pagination --- + + +def test_list_records_pagination(storage: QdrantEdgeStorage) -> None: + records = [ + _rec( + content=f"item {i}", + created_at=datetime(2025, 1, 1) + timedelta(days=i), + ) + for i in range(5) + ] + storage.save(records) + page1 = storage.list_records(limit=2, offset=0) + page2 = storage.list_records(limit=2, offset=2) + assert len(page1) == 2 + assert len(page2) == 2 + # Newest first. + assert page1[0].created_at >= page1[1].created_at + + +def test_list_categories(storage: QdrantEdgeStorage) -> None: + storage.save([ + _rec(categories=["a", "b"]), + _rec(categories=["b", "c"]), + ]) + cats = storage.list_categories() + assert cats.get("b", 0) == 2 + assert cats.get("a", 0) >= 1 + assert cats.get("c", 0) >= 1 + + +# --- Touch & reset --- + + +def test_touch_records(storage: QdrantEdgeStorage) -> None: + r = _rec() + storage.save([r]) + before = storage.get_record(r.id) + assert before is not None + old_accessed = before.last_accessed + storage.touch_records([r.id]) + after = storage.get_record(r.id) + assert after is not None + assert after.last_accessed >= old_accessed + + +def test_reset_full(storage: QdrantEdgeStorage) -> None: + storage.save([_rec(scope="/a"), _rec(scope="/b")]) + assert storage.count() == 2 + storage.reset() + assert storage.count() == 0 + + +def test_reset_scoped(storage: QdrantEdgeStorage) -> None: + storage.save([_rec(scope="/a"), _rec(scope="/b")]) + storage.reset(scope_prefix="/a") + assert storage.count() == 1 + + +# --- Dual-shard & sync --- + + +def test_flush_to_central(tmp_path: Path) -> None: + s = _make_storage(str(tmp_path / "edge")) + s.save([_rec(content="to sync")]) + assert s._local_has_data + s.flush_to_central() + assert not s._local_has_data + assert not s._local_path.exists() + # Central should have the record. + assert s.count() == 1 + + +def test_dual_shard_search(tmp_path: Path) -> None: + s = _make_storage(str(tmp_path / "edge")) + # Save and flush to central. + s.save([_rec(content="central record", scope="/a")]) + s.flush_to_central() + # Save to local only. + s._closed = False # Reset for continued use. + s.save([_rec(content="local record", scope="/b")]) + # Search should find both. + results = s.search([0.1, 0.2, 0.3, 0.4], limit=10) + assert len(results) == 2 + contents = {r.content for r, _ in results} + assert "central record" in contents + assert "local record" in contents + + +def test_close_lifecycle(tmp_path: Path) -> None: + s = _make_storage(str(tmp_path / "edge")) + s.save([_rec(content="persisted")]) + s.close() + # Reopen a new storage — should find the record in central. + s2 = _make_storage(str(tmp_path / "edge")) + results = s2.search([0.1, 0.2, 0.3, 0.4], limit=5) + assert len(results) == 1 + assert results[0][0].content == "persisted" + s2.close() + + +def test_orphaned_shard_cleanup(tmp_path: Path) -> None: + base = tmp_path / "edge" + # Create a fake orphaned shard using a PID that doesn't exist. + fake_pid = 99999999 + s1 = _make_storage(str(base)) + # Manually create a shard at the orphaned path. + orphan_path = base / f"worker-{fake_pid}" + orphan_path.mkdir(parents=True, exist_ok=True) + from qdrant_edge import ( + EdgeConfig, + EdgeShard, + EdgeVectorParams, + Distance, + Point, + UpdateOperation, + ) + + config = EdgeConfig( + vectors={"memory": EdgeVectorParams(size=4, distance=Distance.Cosine)} + ) + orphan = EdgeShard.create(str(orphan_path), config) + orphan.update( + UpdateOperation.upsert_points([ + Point( + id=12345, + vector={"memory": [0.5, 0.5, 0.5, 0.5]}, + payload={ + "record_id": "orphan-uuid", + "content": "orphaned", + "scope": "/", + "scope_ancestors": ["/"], + "categories": [], + "metadata": {}, + "importance": 0.5, + "created_at": datetime.now(timezone.utc).replace(tzinfo=None).isoformat(), + "last_accessed": datetime.now(timezone.utc).replace(tzinfo=None).isoformat(), + "source": "", + "private": False, + }, + ) + ]) + ) + orphan.flush() + orphan.close() + s1.close() + + # Creating a new storage should detect and recover the orphaned shard. + s2 = _make_storage(str(base)) + assert not orphan_path.exists() + # The orphaned record should now be in central. + results = s2.search([0.5, 0.5, 0.5, 0.5], limit=5) + assert len(results) >= 1 + assert any(r.content == "orphaned" for r, _ in results) + s2.close() + + +# --- Integration with Memory class --- + + +def test_memory_with_qdrant_edge(tmp_path: Path) -> None: + from crewai.memory.unified_memory import Memory + + mock_embedder = MagicMock() + mock_embedder.side_effect = lambda texts: [[0.1, 0.2, 0.3, 0.4] for _ in texts] + + storage = _make_storage(str(tmp_path / "edge")) + m = Memory( + storage=storage, + llm=MagicMock(), + embedder=mock_embedder, + ) + r = m.remember( + "We decided to use Qdrant Edge.", + scope="/project", + categories=["decision"], + importance=0.7, + ) + assert r.content == "We decided to use Qdrant Edge." + + matches = m.recall("Qdrant", scope="/project", limit=5, depth="shallow") + assert len(matches) >= 1 + m.close() + + +def test_memory_string_storage_qdrant_edge(tmp_path: Path) -> None: + """Test that storage='qdrant-edge' string instantiation works.""" + import os + + os.environ["CREWAI_STORAGE_DIR"] = str(tmp_path) + try: + from crewai.memory.unified_memory import Memory + + mock_embedder = MagicMock() + mock_embedder.side_effect = lambda texts: [[0.1, 0.2, 0.3, 0.4] for _ in texts] + + m = Memory( + storage="qdrant-edge", + llm=MagicMock(), + embedder=mock_embedder, + ) + from crewai.memory.storage.qdrant_edge_storage import QdrantEdgeStorage + + assert isinstance(m._storage, QdrantEdgeStorage) + m.close() + finally: + os.environ.pop("CREWAI_STORAGE_DIR", None) diff --git a/uv.lock b/uv.lock index 5eed2bdca..ced50114f 100644 --- a/uv.lock +++ b/uv.lock @@ -1205,6 +1205,9 @@ pandas = [ qdrant = [ { name = "qdrant-client", extra = ["fastembed"] }, ] +qdrant-edge = [ + { name = "qdrant-edge-py" }, +] tools = [ { name = "crewai-tools" }, ] @@ -1259,6 +1262,7 @@ requires-dist = [ { name = "python-dotenv", specifier = "~=1.1.1" }, { name = "pyyaml", specifier = "~=6.0" }, { name = "qdrant-client", extras = ["fastembed"], marker = "extra == 'qdrant'", specifier = "~=1.14.3" }, + { name = "qdrant-edge-py", marker = "extra == 'qdrant-edge'", specifier = ">=0.6.0" }, { name = "regex", specifier = "~=2026.1.15" }, { name = "textual", specifier = ">=7.5.0" }, { name = "tiktoken", marker = "extra == 'embeddings'", specifier = "~=0.8.0" }, @@ -1268,7 +1272,7 @@ requires-dist = [ { name = "uv", specifier = "~=0.9.13" }, { name = "voyageai", marker = "extra == 'voyageai'", specifier = "~=0.3.5" }, ] -provides-extras = ["a2a", "anthropic", "aws", "azure-ai-inference", "bedrock", "docling", "embeddings", "file-processing", "google-genai", "litellm", "mem0", "openpyxl", "pandas", "qdrant", "tools", "voyageai", "watson"] +provides-extras = ["a2a", "anthropic", "aws", "azure-ai-inference", "bedrock", "docling", "embeddings", "file-processing", "google-genai", "litellm", "mem0", "openpyxl", "pandas", "qdrant", "qdrant-edge", "tools", "voyageai", "watson"] [[package]] name = "crewai-devtools" @@ -6613,6 +6617,27 @@ fastembed = [ { name = "fastembed", version = "0.7.4", source = { registry = "https://pypi.org/simple" }, marker = "python_full_version < '3.13'" }, ] +[[package]] +name = "qdrant-edge-py" +version = "0.6.0" +source = { registry = "https://pypi.org/simple" } +wheels = [ + { url = "https://files.pythonhosted.org/packages/1c/72/fce3df4e4b8882b5b00ab3d0a574bbeee2d39a8e520ccf246f456effd185/qdrant_edge_py-0.6.0-cp310-abi3-macosx_10_12_x86_64.whl", hash = "sha256:c9d463e7fa81541d60ab8671e6e92a9afd8c4a0e2cfb7e13ea8f5d76e70b877a", size = 9728290, upload-time = "2026-03-19T21:16:15.03Z" }, + { url = "https://files.pythonhosted.org/packages/41/99/70f4e87f7f2ef68c5f92104b914c0e756c22b4bd19957de30a213dadff22/qdrant_edge_py-0.6.0-cp310-abi3-macosx_11_0_arm64.whl", hash = "sha256:a18b0bf0355260466bb8d453f2cedc7a9e4f6a2e9d9c58489b859150a3c7e0a6", size = 9203390, upload-time = "2026-03-19T21:16:17.255Z" }, + { url = "https://files.pythonhosted.org/packages/80/55/998ea744a4cef59c69e86b7b2b57ca2f2d4b0f86c212c7b43dd90cc6360e/qdrant_edge_py-0.6.0-cp310-abi3-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:cda53f31d8693d090ec564e6761037f57af6f342ac2eef82e1c160c00d80f331", size = 10287388, upload-time = "2026-03-19T21:16:19.215Z" }, + { url = "https://files.pythonhosted.org/packages/40/d2/9e24a9c57699fe6df9a4f3b6cd0d4c3c9f0bfdbd502a28d25fdfadd44ab5/qdrant_edge_py-0.6.0-cp310-abi3-manylinux_2_28_aarch64.whl", hash = "sha256:80c5e8f8cf650e422a3d313e394bde2760c6206914cd9d6142c9c5e730a76639", size = 9752632, upload-time = "2026-03-19T21:16:21.409Z" }, + { url = "https://files.pythonhosted.org/packages/0c/3c/a01840efcae392e5a376a483b9a19705ed0f5bc030befbe3d25b58a6d3d4/qdrant_edge_py-0.6.0-cp310-abi3-manylinux_2_28_x86_64.whl", hash = "sha256:d2ab0d209f693fd0d5225072441ed47eccee4f7044470a293c54a3ffdf963cfc", size = 10287245, upload-time = "2026-03-19T21:16:24.366Z" }, + { url = "https://files.pythonhosted.org/packages/7a/45/a3ec5e7d36c5dd4510e4f90d0adaf6aa3e66cff35884ff3edefce240fd77/qdrant_edge_py-0.6.0-cp310-abi3-musllinux_1_2_aarch64.whl", hash = "sha256:9abd0c3aedfed380d4c4a82626004b746bd05cb6a8e28e1b2fe7467726dc8840", size = 9935881, upload-time = "2026-03-19T21:16:26.384Z" }, + { url = "https://files.pythonhosted.org/packages/66/0d/43c9033fbb12f0858d5af73b842acb02b3208fe1a31882def2ef23fd560c/qdrant_edge_py-0.6.0-cp310-abi3-musllinux_1_2_x86_64.whl", hash = "sha256:ea51a917fc1b927d799d60e166337b6837ee3da39c23d4dc736b82b67497ff12", size = 10507046, upload-time = "2026-03-19T21:16:28.536Z" }, + { url = "https://files.pythonhosted.org/packages/73/33/b2ead1c51a59d31d19418e6d6ca8ea3ce0f32f76efdd48248a1a3791357f/qdrant_edge_py-0.6.0-cp310-abi3-win_amd64.whl", hash = "sha256:d8376e30b53fbb5d9ac8b0aea683173096d7a775b351110aee4337460c906e71", size = 9905482, upload-time = "2026-03-19T21:16:30.555Z" }, + { url = "https://files.pythonhosted.org/packages/09/be/a054ac8902e942b0d44e27e8c0e4d3593a34bb143726aa3d9bebd215e7f7/qdrant_edge_py-0.6.0-pp311-pypy311_pp73-macosx_10_12_x86_64.whl", hash = "sha256:6e94804d9aa0c973fe25c83aec16da8c0f9e6a955a0cb1668bd972e1ca4b5604", size = 9724896, upload-time = "2026-03-19T21:16:32.793Z" }, + { url = "https://files.pythonhosted.org/packages/19/30/285eed25d8bab071b9867937b1e0fdc002c0c1180ff43476e5044029e73c/qdrant_edge_py-0.6.0-pp311-pypy311_pp73-macosx_11_0_arm64.whl", hash = "sha256:2ca40da1fa22ff4fd05e669d76c1087d3354486bcb685e9b07b1ca0ab5ef6b97", size = 9199009, upload-time = "2026-03-19T21:16:34.954Z" }, + { url = "https://files.pythonhosted.org/packages/41/d7/b729bbd887476a0a3040fc95d2548e519601d69b2f9d7ece83daf7958372/qdrant_edge_py-0.6.0-pp311-pypy311_pp73-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:12fde5356eeb83ce8031a339ca73ea0a1a9b98927843f5bf7fa5c0412ca5ff79", size = 10279079, upload-time = "2026-03-19T21:16:36.876Z" }, + { url = "https://files.pythonhosted.org/packages/74/2e/68ef2346b6971b8b4d6b479099618dc2879d8c2e357065f8910aeb8b6ed5/qdrant_edge_py-0.6.0-pp311-pypy311_pp73-manylinux_2_28_aarch64.whl", hash = "sha256:c110af3ddbd4a5dae0421457e4a6f1f83c24411ea1187d557367ef5499cb6bef", size = 9746991, upload-time = "2026-03-19T21:16:38.968Z" }, + { url = "https://files.pythonhosted.org/packages/cd/46/3bfcc5e13d1a7d110a2d1ecf86c63a781e71e543712232be59d7a3f34e96/qdrant_edge_py-0.6.0-pp311-pypy311_pp73-manylinux_2_28_x86_64.whl", hash = "sha256:839651466c217bb8f684a3a0b9ad0726c670fcc734b552eef3ad76fbb4f5a12b", size = 10282664, upload-time = "2026-03-19T21:16:40.952Z" }, + { url = "https://files.pythonhosted.org/packages/80/54/7ba6bbaa2b53a188b0a43a6c063007e9a58afa3e35326f63518efbc6f5e8/qdrant_edge_py-0.6.0-pp311-pypy311_pp73-win_amd64.whl", hash = "sha256:c7665230dc4a2412412765fbdf9053e32b32f4c60579881ed68140b4d0ba6915", size = 9901015, upload-time = "2026-03-19T21:16:43.407Z" }, +] + [[package]] name = "questionary" version = "2.1.1" From 2267b96e892ed01788452faf29bbe6abbc76b717 Mon Sep 17 00:00:00 2001 From: Greyson LaLonde Date: Wed, 25 Mar 2026 23:49:12 +0800 Subject: [PATCH 12/25] feat: bump versions to 1.12.0a2 --- lib/crewai-files/src/crewai_files/__init__.py | 2 +- lib/crewai-tools/pyproject.toml | 2 +- lib/crewai-tools/src/crewai_tools/__init__.py | 2 +- lib/crewai/pyproject.toml | 2 +- lib/crewai/src/crewai/__init__.py | 2 +- lib/crewai/src/crewai/cli/templates/crew/pyproject.toml | 2 +- lib/crewai/src/crewai/cli/templates/flow/pyproject.toml | 2 +- lib/crewai/src/crewai/cli/templates/tool/pyproject.toml | 2 +- lib/devtools/src/crewai_devtools/__init__.py | 2 +- 9 files changed, 9 insertions(+), 9 deletions(-) diff --git a/lib/crewai-files/src/crewai_files/__init__.py b/lib/crewai-files/src/crewai_files/__init__.py index b2cc6f759..927232168 100644 --- a/lib/crewai-files/src/crewai_files/__init__.py +++ b/lib/crewai-files/src/crewai_files/__init__.py @@ -152,4 +152,4 @@ __all__ = [ "wrap_file_source", ] -__version__ = "1.12.0a1" +__version__ = "1.12.0a2" diff --git a/lib/crewai-tools/pyproject.toml b/lib/crewai-tools/pyproject.toml index abe95dd11..47ae3bebb 100644 --- a/lib/crewai-tools/pyproject.toml +++ b/lib/crewai-tools/pyproject.toml @@ -11,7 +11,7 @@ dependencies = [ "pytube~=15.0.0", "requests~=2.32.5", "docker~=7.1.0", - "crewai==1.12.0a1", + "crewai==1.12.0a2", "tiktoken~=0.8.0", "beautifulsoup4~=4.13.4", "python-docx~=1.2.0", diff --git a/lib/crewai-tools/src/crewai_tools/__init__.py b/lib/crewai-tools/src/crewai_tools/__init__.py index aeb493b78..ea14bfc93 100644 --- a/lib/crewai-tools/src/crewai_tools/__init__.py +++ b/lib/crewai-tools/src/crewai_tools/__init__.py @@ -309,4 +309,4 @@ __all__ = [ "ZapierActionTools", ] -__version__ = "1.12.0a1" +__version__ = "1.12.0a2" diff --git a/lib/crewai/pyproject.toml b/lib/crewai/pyproject.toml index 2a80698b5..cd3809b12 100644 --- a/lib/crewai/pyproject.toml +++ b/lib/crewai/pyproject.toml @@ -54,7 +54,7 @@ Repository = "https://github.com/crewAIInc/crewAI" [project.optional-dependencies] tools = [ - "crewai-tools==1.12.0a1", + "crewai-tools==1.12.0a2", ] embeddings = [ "tiktoken~=0.8.0" diff --git a/lib/crewai/src/crewai/__init__.py b/lib/crewai/src/crewai/__init__.py index 08fa2f98d..dcaa55f84 100644 --- a/lib/crewai/src/crewai/__init__.py +++ b/lib/crewai/src/crewai/__init__.py @@ -42,7 +42,7 @@ def _suppress_pydantic_deprecation_warnings() -> None: _suppress_pydantic_deprecation_warnings() -__version__ = "1.12.0a1" +__version__ = "1.12.0a2" _telemetry_submitted = False diff --git a/lib/crewai/src/crewai/cli/templates/crew/pyproject.toml b/lib/crewai/src/crewai/cli/templates/crew/pyproject.toml index 2590a1c49..8ecce0a71 100644 --- a/lib/crewai/src/crewai/cli/templates/crew/pyproject.toml +++ b/lib/crewai/src/crewai/cli/templates/crew/pyproject.toml @@ -5,7 +5,7 @@ description = "{{name}} using crewAI" authors = [{ name = "Your Name", email = "you@example.com" }] requires-python = ">=3.10,<3.14" dependencies = [ - "crewai[tools]==1.12.0a1" + "crewai[tools]==1.12.0a2" ] [project.scripts] diff --git a/lib/crewai/src/crewai/cli/templates/flow/pyproject.toml b/lib/crewai/src/crewai/cli/templates/flow/pyproject.toml index 2f8eda95a..c4d9b4452 100644 --- a/lib/crewai/src/crewai/cli/templates/flow/pyproject.toml +++ b/lib/crewai/src/crewai/cli/templates/flow/pyproject.toml @@ -5,7 +5,7 @@ description = "{{name}} using crewAI" authors = [{ name = "Your Name", email = "you@example.com" }] requires-python = ">=3.10,<3.14" dependencies = [ - "crewai[tools]==1.12.0a1" + "crewai[tools]==1.12.0a2" ] [project.scripts] diff --git a/lib/crewai/src/crewai/cli/templates/tool/pyproject.toml b/lib/crewai/src/crewai/cli/templates/tool/pyproject.toml index 6aca3d7e4..3426991fc 100644 --- a/lib/crewai/src/crewai/cli/templates/tool/pyproject.toml +++ b/lib/crewai/src/crewai/cli/templates/tool/pyproject.toml @@ -5,7 +5,7 @@ description = "Power up your crews with {{folder_name}}" readme = "README.md" requires-python = ">=3.10,<3.14" dependencies = [ - "crewai[tools]==1.12.0a1" + "crewai[tools]==1.12.0a2" ] [tool.crewai] diff --git a/lib/devtools/src/crewai_devtools/__init__.py b/lib/devtools/src/crewai_devtools/__init__.py index 1df857042..b8ca3fb18 100644 --- a/lib/devtools/src/crewai_devtools/__init__.py +++ b/lib/devtools/src/crewai_devtools/__init__.py @@ -1,3 +1,3 @@ """CrewAI development tools.""" -__version__ = "1.12.0a1" +__version__ = "1.12.0a2" From 4d1c041cc1917d4fc37c7e99a409d5fa037e7c11 Mon Sep 17 00:00:00 2001 From: Greyson LaLonde Date: Wed, 25 Mar 2026 23:54:52 +0800 Subject: [PATCH 13/25] docs: update changelog and version for v1.12.0a2 --- docs/ar/changelog.mdx | 19 +++++++++++++++++++ docs/en/changelog.mdx | 19 +++++++++++++++++++ docs/ko/changelog.mdx | 19 +++++++++++++++++++ docs/pt-BR/changelog.mdx | 19 +++++++++++++++++++ 4 files changed, 76 insertions(+) diff --git a/docs/ar/changelog.mdx b/docs/ar/changelog.mdx index 6316b91a6..c8bea9db8 100644 --- a/docs/ar/changelog.mdx +++ b/docs/ar/changelog.mdx @@ -4,6 +4,25 @@ description: "تحديثات المنتج والتحسينات وإصلاحات icon: "clock" mode: "wide" --- + + ## v1.12.0a2 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.12.0a2) + + ## ما الذي تغير + + ### الميزات + - إضافة واجهة تخزين Qdrant Edge لنظام الذاكرة + + ### الوثائق + - تحديث سجل التغييرات والإصدار لـ v1.12.0a1 + + ## المساهمون + + @greysonlalonde + + + ## v1.12.0a1 diff --git a/docs/en/changelog.mdx b/docs/en/changelog.mdx index df519eb04..109b0bed6 100644 --- a/docs/en/changelog.mdx +++ b/docs/en/changelog.mdx @@ -4,6 +4,25 @@ description: "Product updates, improvements, and bug fixes for CrewAI" icon: "clock" mode: "wide" --- + + ## v1.12.0a2 + + [View release on GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.12.0a2) + + ## What's Changed + + ### Features + - Add Qdrant Edge storage backend for memory system + + ### Documentation + - Update changelog and version for v1.12.0a1 + + ## Contributors + + @greysonlalonde + + + ## v1.12.0a1 diff --git a/docs/ko/changelog.mdx b/docs/ko/changelog.mdx index 03b8fc3cd..3e3e4a482 100644 --- a/docs/ko/changelog.mdx +++ b/docs/ko/changelog.mdx @@ -4,6 +4,25 @@ description: "CrewAI의 제품 업데이트, 개선 사항 및 버그 수정" icon: "clock" mode: "wide" --- + + ## v1.12.0a2 + + [GitHub 릴리스 보기](https://github.com/crewAIInc/crewAI/releases/tag/1.12.0a2) + + ## 변경 사항 + + ### 기능 + - 메모리 시스템을 위한 Qdrant Edge 스토리지 백엔드 추가 + + ### 문서 + - v1.12.0a1에 대한 변경 로그 및 버전 업데이트 + + ## 기여자 + + @greysonlalonde + + + ## v1.12.0a1 diff --git a/docs/pt-BR/changelog.mdx b/docs/pt-BR/changelog.mdx index 4d5504e40..fb44d9f04 100644 --- a/docs/pt-BR/changelog.mdx +++ b/docs/pt-BR/changelog.mdx @@ -4,6 +4,25 @@ description: "Atualizações de produto, melhorias e correções do CrewAI" icon: "clock" mode: "wide" --- + + ## v1.12.0a2 + + [Ver release no GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.12.0a2) + + ## O que Mudou + + ### Recursos + - Adicionar backend de armazenamento Qdrant Edge para sistema de memória + + ### Documentação + - Atualizar changelog e versão para v1.12.0a1 + + ## Contribuidores + + @greysonlalonde + + + ## v1.12.0a1 From 195647108664eac5c3deb86d02b2a2efd43b1a0b Mon Sep 17 00:00:00 2001 From: Greyson LaLonde Date: Thu, 26 Mar 2026 03:33:03 +0800 Subject: [PATCH 14/25] fix: resolve multiple bugs in HITL flow system --- .../crewai/flow/async_feedback/providers.py | 2 +- .../src/crewai/flow/async_feedback/types.py | 30 ++++++++- lib/crewai/src/crewai/flow/flow.py | 29 ++++++--- lib/crewai/src/crewai/flow/human_feedback.py | 64 +++++++++++++++---- 4 files changed, 100 insertions(+), 25 deletions(-) diff --git a/lib/crewai/src/crewai/flow/async_feedback/providers.py b/lib/crewai/src/crewai/flow/async_feedback/providers.py index 43443046f..021fbb4a2 100644 --- a/lib/crewai/src/crewai/flow/async_feedback/providers.py +++ b/lib/crewai/src/crewai/flow/async_feedback/providers.py @@ -182,7 +182,7 @@ class ConsoleProvider: console.print(message, style="yellow") console.print() - response = input(">>> \n").strip() + response = input(">>> ").strip() else: response = input(f"{message} ").strip() diff --git a/lib/crewai/src/crewai/flow/async_feedback/types.py b/lib/crewai/src/crewai/flow/async_feedback/types.py index 50bac22a6..911624cd9 100644 --- a/lib/crewai/src/crewai/flow/async_feedback/types.py +++ b/lib/crewai/src/crewai/flow/async_feedback/types.py @@ -63,6 +63,32 @@ class PendingFeedbackContext: llm: dict[str, Any] | str | None = None requested_at: datetime = field(default_factory=datetime.now) + @staticmethod + def _make_json_safe(value: Any) -> Any: + """Convert a value to a JSON-serializable form. + + Handles Pydantic models, dataclasses, and arbitrary objects by + progressively falling back to string representation. + """ + if value is None or isinstance(value, (str, int, float, bool)): + return value + if isinstance(value, (list, tuple)): + return [PendingFeedbackContext._make_json_safe(v) for v in value] + if isinstance(value, dict): + return { + k: PendingFeedbackContext._make_json_safe(v) for k, v in value.items() + } + + from pydantic import BaseModel + + if isinstance(value, BaseModel): + return value.model_dump(mode="json") + import dataclasses + + if dataclasses.is_dataclass(value) and not isinstance(value, type): + return PendingFeedbackContext._make_json_safe(dataclasses.asdict(value)) + return str(value) + def to_dict(self) -> dict[str, Any]: """Serialize context to a dictionary for persistence. @@ -73,11 +99,11 @@ class PendingFeedbackContext: "flow_id": self.flow_id, "flow_class": self.flow_class, "method_name": self.method_name, - "method_output": self.method_output, + "method_output": self._make_json_safe(self.method_output), "message": self.message, "emit": self.emit, "default_outcome": self.default_outcome, - "metadata": self.metadata, + "metadata": self._make_json_safe(self.metadata), "llm": self.llm, "requested_at": self.requested_at.isoformat(), } diff --git a/lib/crewai/src/crewai/flow/flow.py b/lib/crewai/src/crewai/flow/flow.py index 1c1aa90b5..f1e75e617 100644 --- a/lib/crewai/src/crewai/flow/flow.py +++ b/lib/crewai/src/crewai/flow/flow.py @@ -1223,9 +1223,6 @@ class Flow(Generic[T], metaclass=FlowMeta): # Mark that we're resuming execution instance._is_execution_resuming = True - # Mark the method as completed (it ran before pausing) - instance._completed_methods.add(FlowMethodName(pending_context.method_name)) - return instance @property @@ -1380,7 +1377,8 @@ class Flow(Generic[T], metaclass=FlowMeta): self.human_feedback_history.append(result) self.last_human_feedback = result - # Clear pending context after processing + self._completed_methods.add(FlowMethodName(context.method_name)) + self._pending_feedback_context = None # Clear pending feedback from persistence @@ -1403,7 +1401,10 @@ class Flow(Generic[T], metaclass=FlowMeta): # This allows methods to re-execute in loops (e.g., implement_changes → suggest_changes → implement_changes) self._is_execution_resuming = False - final_result: Any = result + if emit and collapsed_outcome is None: + collapsed_outcome = default_outcome or emit[0] + result.outcome = collapsed_outcome + try: if emit and collapsed_outcome: self._method_outputs.append(collapsed_outcome) @@ -1421,7 +1422,8 @@ class Flow(Generic[T], metaclass=FlowMeta): from crewai.flow.async_feedback.types import HumanFeedbackPending if isinstance(e, HumanFeedbackPending): - # Auto-save pending feedback (create default persistence if needed) + self._pending_feedback_context = e.context + if self._persistence is None: from crewai.flow.persistence import SQLiteFlowPersistence @@ -1455,6 +1457,8 @@ class Flow(Generic[T], metaclass=FlowMeta): return e raise + final_result = self._method_outputs[-1] if self._method_outputs else result + # Emit flow finished crewai_event_bus.emit( self, @@ -2314,7 +2318,6 @@ class Flow(Generic[T], metaclass=FlowMeta): if isinstance(e, HumanFeedbackPending): e.context.method_name = method_name - # Auto-save pending feedback (create default persistence if needed) if self._persistence is None: from crewai.flow.persistence import SQLiteFlowPersistence @@ -3133,10 +3136,16 @@ class Flow(Generic[T], metaclass=FlowMeta): if outcome.lower() == response_clean.lower(): return outcome - # Partial match + # Partial match (longest wins, first on length ties) + response_lower = response_clean.lower() + best_outcome: str | None = None + best_len = -1 for outcome in outcomes: - if outcome.lower() in response_clean.lower(): - return outcome + if outcome.lower() in response_lower and len(outcome) > best_len: + best_outcome = outcome + best_len = len(outcome) + if best_outcome is not None: + return best_outcome # Fallback to first outcome logger.warning( diff --git a/lib/crewai/src/crewai/flow/human_feedback.py b/lib/crewai/src/crewai/flow/human_feedback.py index 9bace438e..e43fc3337 100644 --- a/lib/crewai/src/crewai/flow/human_feedback.py +++ b/lib/crewai/src/crewai/flow/human_feedback.py @@ -116,10 +116,11 @@ def _deserialize_llm_from_context( return LLM(model=llm_data) if isinstance(llm_data, dict): - model = llm_data.pop("model", None) + data = dict(llm_data) + model = data.pop("model", None) if not model: return None - return LLM(model=model, **llm_data) + return LLM(model=model, **data) return None @@ -450,12 +451,12 @@ def human_feedback( # -- Core feedback helpers ------------------------------------ - def _request_feedback(flow_instance: Flow[Any], method_output: Any) -> str: - """Request feedback using provider or default console.""" + def _build_feedback_context( + flow_instance: Flow[Any], method_output: Any + ) -> tuple[Any, Any]: + """Build the PendingFeedbackContext and resolve the effective provider.""" from crewai.flow.async_feedback.types import PendingFeedbackContext - # Build context for provider - # Use flow_id property which handles both dict and BaseModel states context = PendingFeedbackContext( flow_id=flow_instance.flow_id or "unknown", flow_class=f"{flow_instance.__class__.__module__}.{flow_instance.__class__.__name__}", @@ -468,15 +469,53 @@ def human_feedback( llm=llm if isinstance(llm, str) else _serialize_llm_for_context(llm), ) - # Determine effective provider: effective_provider = provider if effective_provider is None: from crewai.flow.flow_config import flow_config effective_provider = flow_config.hitl_provider + return context, effective_provider + + def _request_feedback(flow_instance: Flow[Any], method_output: Any) -> str: + """Request feedback using provider or default console (sync).""" + context, effective_provider = _build_feedback_context( + flow_instance, method_output + ) + if effective_provider is not None: - return effective_provider.request_feedback(context, flow_instance) + feedback_result = effective_provider.request_feedback( + context, flow_instance + ) + if asyncio.iscoroutine(feedback_result): + raise TypeError( + f"Provider {type(effective_provider).__name__}.request_feedback() " + "returned a coroutine in a sync flow method. Use an async flow " + "method or a synchronous provider." + ) + return str(feedback_result) + return flow_instance._request_human_feedback( + message=message, + output=method_output, + metadata=metadata, + emit=emit, + ) + + async def _request_feedback_async( + flow_instance: Flow[Any], method_output: Any + ) -> str: + """Request feedback, awaiting the provider if it returns a coroutine.""" + context, effective_provider = _build_feedback_context( + flow_instance, method_output + ) + + if effective_provider is not None: + feedback_result = effective_provider.request_feedback( + context, flow_instance + ) + if asyncio.iscoroutine(feedback_result): + return str(await feedback_result) + return str(feedback_result) return flow_instance._request_human_feedback( message=message, output=method_output, @@ -524,10 +563,11 @@ def human_feedback( flow_instance.human_feedback_history.append(result) flow_instance.last_human_feedback = result - # Return based on mode if emit: - # Return outcome for routing - return collapsed_outcome # type: ignore[return-value] + if collapsed_outcome is None: + collapsed_outcome = default_outcome or emit[0] + result.outcome = collapsed_outcome + return collapsed_outcome return result if asyncio.iscoroutinefunction(func): @@ -540,7 +580,7 @@ def human_feedback( if learn and getattr(self, "memory", None) is not None: method_output = _pre_review_with_lessons(self, method_output) - raw_feedback = _request_feedback(self, method_output) + raw_feedback = await _request_feedback_async(self, method_output) result = _process_feedback(self, method_output, raw_feedback) # Distill: extract lessons from output + feedback, store in memory From d86707da3d8c39514e3974aecb898c2a42bca389 Mon Sep 17 00:00:00 2001 From: Tiago Freire Date: Wed, 25 Mar 2026 16:00:05 -0400 Subject: [PATCH 15/25] Fix: bad credentials for traces batch push (404) (#4947) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ## Summary ### Core fixes
Fix silent 404 cascade on trace event send When `_initialize_backend_batch` failed, `trace_batch_id` was left populated with a client-generated UUID never registered server-side. All subsequent event sends hit a non-existent batch endpoint and returned 404. Now all three failure paths (None response, non-2xx status, exception) clear `trace_batch_id`.
Fix first-time deferred batch init silently skipped First-time users have `is_tracing_enabled_in_context() = False` by design. This caused `_initialize_backend_batch` to return early without creating the batch, and `finalize_batch` to skip finalization (same guard). The first-time handler now passes `skip_context_check=True` to bypass both guards, calls `_finalize_backend_batch` directly, gates `backend_initialized` on actual success, checks `_send_events_to_backend` return status (marking batch as failed on 500), captures event count/duration/batch ID before they're consumed by send/finalize, and cleans up all singleton state via `_reset_batch_state()` on every exit path.
Sync is_current_batch_ephemeral on batch creation success When the batch is successfully created on the server, `is_current_batch_ephemeral` is now synced with the actual `use_ephemeral` value used. This prevents endpoint mismatches where the batch was created on one endpoint but events and finalization were sent to a different one, resulting in 404.
Route mark_trace_batch_as_failed to correct endpoint for ephemeral batches `mark_trace_batch_as_failed` always routed to the non-ephemeral endpoint (`/tracing/batches/{id}`), causing 404s when called on ephemeral batches — the same class of endpoint mismatch this PR aims to fix. Added `mark_ephemeral_trace_batch_as_failed` to `PlusAPI` and a `_mark_batch_as_failed` helper on `TraceBatchManager` that routes based on `is_current_batch_ephemeral`.
Gate backend_initialized on actual init success (non-first-time path) On the non-first-time path, `backend_initialized` was set to `True` unconditionally after `_initialize_backend_batch` returned. With the new failure-path cleanup that clears `trace_batch_id`, this created an inconsistent state: `backend_initialized=True` + `trace_batch_id=None`. Now set via `self.trace_batch_id is not None`.
### Resilience improvements
Retry transient failures on batch creation `_initialize_backend_batch` now retries up to 2 times with 200ms backoff on transient failures (None response, 5xx, network errors). Non-transient 4xx errors are not retried. The short backoff minimizes lock hold time on the non-first-time path where `_batch_ready_cv` is held.
Fall back to ephemeral on server auth rejection When the non-ephemeral endpoint returns 401/403 (expired token, revoked credentials, key rotation), the client automatically switches to ephemeral tracing instead of losing traces. The fallback forwards `skip_context_check` and is guarded against infinite recursion — if ephemeral also fails, `trace_batch_id` is cleared normally.
Fix action-event race initializing batch as non-ephemeral `_handle_action_event` called `batch_manager.initialize_batch()` directly, defaulting `use_ephemeral=False`. When a `DefaultEnvEvent` or `LLMCallStartedEvent` fired before `CrewKickoffStartedEvent` in the thread pool, the batch was locked in as non-ephemeral. Now routes through `_initialize_batch()` which computes `use_ephemeral` from `_check_authenticated()`.
Guard _mark_batch_as_failed against cascading network errors When `_finalize_backend_batch` failed with a network error (e.g. `[Errno 54] Connection reset by peer`), the exception handler called `_mark_batch_as_failed` — which also makes an HTTP request on the same dead connection. That second failure was unhandled. Now wrapped in a try/except so it logs at debug level instead of propagating.
Design decision: first-time users always use ephemeral First-time trace collection **always creates ephemeral batches**, regardless of authentication status. This is intentional: 1. **The first-time handler UX is built around ephemeral traces** — it displays an access code, a 24-hour expiry link, and opens the browser to the ephemeral trace viewer. Non-ephemeral batches don't produce these artifacts, so the handler would fall through to the "Local Traces Collected" fallback even when traces were successfully sent. 2. **The server handles account linking automatically** — `LinkEphemeralTracesJob` runs on user signup and migrates ephemeral traces to permanent records. Logged-in users can access their traces via their dashboard regardless. 3. **Checking auth during batch setup broke event collection** — moving `_check_authenticated()` into `_initialize_batch` caused the batch initialization to fail silently during the flow/crew start event handler, preventing all event collection. Keeping the first-time path fast and side-effect-free preserves event collection. The auth check is deferred to the non-first-time path (second run onwards), where `is_tracing_enabled_in_context()` is `True` and the normal tracing pipeline handles everything — including the 401/403 ephemeral fallback.
### Manual tests
Matrix | Scenario | First run | Second run | |----------|-----------|------------| | Logged out, fresh `.crewai_user.json` | Ephemeral trace created, URL returned | Ephemeral trace created, URL returned | | Logged in, fresh `.crewai_user.json` | Ephemeral trace created, URL returned | Trace batch finalized, URL returned | | Flow execution | Tested with `poem_flow` | Tested with `poem_flow` | | Crew execution | Tested with `hitl_crew` | Tested with `hitl_crew` |
--- lib/crewai/src/crewai/cli/plus_api.py | 10 + .../tracing/first_time_trace_handler.py | 62 +- .../listeners/tracing/trace_batch_manager.py | 82 +- .../listeners/tracing/trace_listener.py | 16 +- .../crewai/events/utils/console_formatter.py | 9 + lib/crewai/tests/tracing/test_tracing.py | 718 ++++++++++++++++++ 6 files changed, 869 insertions(+), 28 deletions(-) diff --git a/lib/crewai/src/crewai/cli/plus_api.py b/lib/crewai/src/crewai/cli/plus_api.py index e32e5220d..665221f1e 100644 --- a/lib/crewai/src/crewai/cli/plus_api.py +++ b/lib/crewai/src/crewai/cli/plus_api.py @@ -196,6 +196,16 @@ class PlusAPI: timeout=30, ) + def mark_ephemeral_trace_batch_as_failed( + self, trace_batch_id: str, error_message: str + ) -> httpx.Response: + return self._make_request( + "PATCH", + f"{self.EPHEMERAL_TRACING_RESOURCE}/batches/{trace_batch_id}", + json={"status": "failed", "failure_reason": error_message}, + timeout=30, + ) + def get_mcp_configs(self, slugs: list[str]) -> httpx.Response: """Get MCP server configurations for the given slugs.""" return self._make_request( diff --git a/lib/crewai/src/crewai/events/listeners/tracing/first_time_trace_handler.py b/lib/crewai/src/crewai/events/listeners/tracing/first_time_trace_handler.py index 715642a6e..436d50c27 100644 --- a/lib/crewai/src/crewai/events/listeners/tracing/first_time_trace_handler.py +++ b/lib/crewai/src/crewai/events/listeners/tracing/first_time_trace_handler.py @@ -1,3 +1,4 @@ +from datetime import datetime, timezone import logging import uuid import webbrowser @@ -100,20 +101,50 @@ class FirstTimeTraceHandler: user_context=user_context, execution_metadata=execution_metadata, use_ephemeral=True, + skip_context_check=True, ) + + if not self.batch_manager.trace_batch_id: + self._gracefully_fail( + "Backend batch creation failed, cannot send events." + ) + self._reset_batch_state() + return + self.batch_manager.backend_initialized = True - if self.batch_manager.event_buffer: - self.batch_manager._send_events_to_backend() + # Capture values before send/finalize consume them + events_count = len(self.batch_manager.event_buffer) + batch_id = self.batch_manager.trace_batch_id + # Read duration non-destructively — _finalize_backend_batch will consume it + start_time = self.batch_manager.execution_start_times.get("execution") + duration_ms = ( + int((datetime.now(timezone.utc) - start_time).total_seconds() * 1000) + if start_time + else 0 + ) - self.batch_manager.finalize_batch() + if self.batch_manager.event_buffer: + send_status = self.batch_manager._send_events_to_backend() + if send_status == 500 and self.batch_manager.trace_batch_id: + self.batch_manager._mark_batch_as_failed( + self.batch_manager.trace_batch_id, + "Error sending events to backend", + ) + self._reset_batch_state() + return + + self.batch_manager._finalize_backend_batch(events_count) self.ephemeral_url = self.batch_manager.ephemeral_trace_url if not self.ephemeral_url: - self._show_local_trace_message() + self._show_local_trace_message(events_count, duration_ms, batch_id) + + self._reset_batch_state() except Exception as e: self._gracefully_fail(f"Backend initialization failed: {e}") + self._reset_batch_state() def _display_ephemeral_trace_link(self) -> None: """Display the ephemeral trace link to the user and automatically open browser.""" @@ -185,6 +216,19 @@ To enable tracing later, do any one of these: console.print(panel) console.print() + def _reset_batch_state(self) -> None: + """Reset batch manager state to allow future executions to re-initialize.""" + if not self.batch_manager: + return + self.batch_manager.batch_owner_type = None + self.batch_manager.batch_owner_id = None + self.batch_manager.current_batch = None + self.batch_manager.event_buffer.clear() + self.batch_manager.trace_batch_id = None + self.batch_manager.is_current_batch_ephemeral = False + self.batch_manager.backend_initialized = False + self.batch_manager._cleanup_batch_data() + def _gracefully_fail(self, error_message: str) -> None: """Handle errors gracefully without disrupting user experience.""" console = Console() @@ -192,7 +236,9 @@ To enable tracing later, do any one of these: logger.debug(f"First-time trace error: {error_message}") - def _show_local_trace_message(self) -> None: + def _show_local_trace_message( + self, events_count: int = 0, duration_ms: int = 0, batch_id: str | None = None + ) -> None: """Show message when traces were collected locally but couldn't be uploaded.""" if self.batch_manager is None: return @@ -203,9 +249,9 @@ To enable tracing later, do any one of these: 📊 Your execution traces were collected locally! Unfortunately, we couldn't upload them to the server right now, but here's what we captured: -• {len(self.batch_manager.event_buffer)} trace events -• Execution duration: {self.batch_manager.calculate_duration("execution")}ms -• Batch ID: {self.batch_manager.trace_batch_id} +• {events_count} trace events +• Execution duration: {duration_ms}ms +• Batch ID: {batch_id} ✅ Tracing has been enabled for future runs! Your preference has been saved. Future Crew/Flow executions will automatically collect traces. diff --git a/lib/crewai/src/crewai/events/listeners/tracing/trace_batch_manager.py b/lib/crewai/src/crewai/events/listeners/tracing/trace_batch_manager.py index da25792fb..1a25b68a9 100644 --- a/lib/crewai/src/crewai/events/listeners/tracing/trace_batch_manager.py +++ b/lib/crewai/src/crewai/events/listeners/tracing/trace_batch_manager.py @@ -2,6 +2,7 @@ from dataclasses import dataclass, field from datetime import datetime, timezone from logging import getLogger from threading import Condition, Lock +import time from typing import Any import uuid @@ -98,7 +99,7 @@ class TraceBatchManager: self._initialize_backend_batch( user_context, execution_metadata, use_ephemeral ) - self.backend_initialized = True + self.backend_initialized = self.trace_batch_id is not None self._batch_ready_cv.notify_all() return self.current_batch @@ -108,14 +109,15 @@ class TraceBatchManager: user_context: dict[str, str], execution_metadata: dict[str, Any], use_ephemeral: bool = False, + skip_context_check: bool = False, ) -> None: """Send batch initialization to backend""" - if not is_tracing_enabled_in_context(): - return + if not skip_context_check and not is_tracing_enabled_in_context(): + return None if not self.plus_api or not self.current_batch: - return + return None try: payload = { @@ -142,19 +144,53 @@ class TraceBatchManager: payload["ephemeral_trace_id"] = self.current_batch.batch_id payload["user_identifier"] = get_user_id() - response = ( - self.plus_api.initialize_ephemeral_trace_batch(payload) - if use_ephemeral - else self.plus_api.initialize_trace_batch(payload) - ) + max_retries = 1 + response = None + + try: + for attempt in range(max_retries + 1): + response = ( + self.plus_api.initialize_ephemeral_trace_batch(payload) + if use_ephemeral + else self.plus_api.initialize_trace_batch(payload) + ) + if response is not None and response.status_code < 500: + break + if attempt < max_retries: + logger.debug( + f"Trace batch init attempt {attempt + 1} failed " + f"(status={response.status_code if response else 'None'}), retrying..." + ) + time.sleep(0.2) + except Exception as e: + logger.warning( + f"Error initializing trace batch: {e}. Continuing without tracing." + ) + self.trace_batch_id = None + return None if response is None: logger.warning( "Trace batch initialization failed gracefully. Continuing without tracing." ) - return + self.trace_batch_id = None + return None + + # Fall back to ephemeral on auth failure (expired/revoked token) + if response.status_code in [401, 403] and not use_ephemeral: + logger.warning( + "Auth rejected by server, falling back to ephemeral tracing." + ) + self.is_current_batch_ephemeral = True + return self._initialize_backend_batch( + user_context, + execution_metadata, + use_ephemeral=True, + skip_context_check=skip_context_check, + ) if response.status_code in [201, 200]: + self.is_current_batch_ephemeral = use_ephemeral response_data = response.json() self.trace_batch_id = ( response_data["trace_id"] @@ -165,11 +201,22 @@ class TraceBatchManager: logger.warning( f"Trace batch initialization returned status {response.status_code}. Continuing without tracing." ) + self.trace_batch_id = None except Exception as e: logger.warning( f"Error initializing trace batch: {e}. Continuing without tracing." ) + self.trace_batch_id = None + + def _mark_batch_as_failed(self, trace_batch_id: str, error_message: str) -> None: + """Mark a trace batch as failed, routing to the correct endpoint.""" + if self.is_current_batch_ephemeral: + self.plus_api.mark_ephemeral_trace_batch_as_failed( + trace_batch_id, error_message + ) + else: + self.plus_api.mark_trace_batch_as_failed(trace_batch_id, error_message) def begin_event_processing(self) -> None: """Mark that an event handler started processing (for synchronization).""" @@ -260,7 +307,7 @@ class TraceBatchManager: logger.error( "Event handler timeout - marking batch as failed due to incomplete events" ) - self.plus_api.mark_trace_batch_as_failed( + self._mark_batch_as_failed( self.trace_batch_id, "Timeout waiting for event handlers - events incomplete", ) @@ -284,7 +331,7 @@ class TraceBatchManager: events_sent_to_backend_status = self._send_events_to_backend() self.event_buffer = original_buffer if events_sent_to_backend_status == 500 and self.trace_batch_id: - self.plus_api.mark_trace_batch_as_failed( + self._mark_batch_as_failed( self.trace_batch_id, "Error sending events to backend" ) return None @@ -364,13 +411,16 @@ class TraceBatchManager: logger.error( f"❌ Failed to finalize trace batch: {response.status_code} - {response.text}" ) - self.plus_api.mark_trace_batch_as_failed( - self.trace_batch_id, response.text - ) + self._mark_batch_as_failed(self.trace_batch_id, response.text) except Exception as e: logger.error(f"❌ Error finalizing trace batch: {e}") - self.plus_api.mark_trace_batch_as_failed(self.trace_batch_id, str(e)) + try: + self._mark_batch_as_failed(self.trace_batch_id, str(e)) + except Exception: + logger.debug( + "Could not mark trace batch as failed (network unavailable)" + ) def _cleanup_batch_data(self) -> None: """Clean up batch data after successful finalization to free memory""" diff --git a/lib/crewai/src/crewai/events/listeners/tracing/trace_listener.py b/lib/crewai/src/crewai/events/listeners/tracing/trace_listener.py index b86d77aa1..9d81f1d55 100644 --- a/lib/crewai/src/crewai/events/listeners/tracing/trace_listener.py +++ b/lib/crewai/src/crewai/events/listeners/tracing/trace_listener.py @@ -235,8 +235,11 @@ class TraceCollectionListener(BaseEventListener): @event_bus.on(FlowStartedEvent) def on_flow_started(source: Any, event: FlowStartedEvent) -> None: - if not self.batch_manager.is_batch_initialized(): - self._initialize_flow_batch(source, event) + # Always call _initialize_flow_batch to claim ownership. + # If batch was already initialized by a concurrent action event + # (race condition), initialize_batch() returns early but + # batch_owner_type is still correctly set to "flow". + self._initialize_flow_batch(source, event) self._handle_trace_event("flow_started", source, event) @event_bus.on(MethodExecutionStartedEvent) @@ -266,7 +269,12 @@ class TraceCollectionListener(BaseEventListener): @event_bus.on(CrewKickoffStartedEvent) def on_crew_started(source: Any, event: CrewKickoffStartedEvent) -> None: - if not self.batch_manager.is_batch_initialized(): + if self.batch_manager.batch_owner_type != "flow": + # Always call _initialize_crew_batch to claim ownership. + # If batch was already initialized by a concurrent action event + # (race condition with DefaultEnvEvent), initialize_batch() returns + # early but batch_owner_type is still correctly set to "crew". + # Skip only when a parent flow already owns the batch. self._initialize_crew_batch(source, event) self._handle_trace_event("crew_kickoff_started", source, event) @@ -772,7 +780,7 @@ class TraceCollectionListener(BaseEventListener): "crew_name": getattr(source, "name", "Unknown Crew"), "crewai_version": get_crewai_version(), } - self.batch_manager.initialize_batch(user_context, execution_metadata) + self._initialize_batch(user_context, execution_metadata) self.batch_manager.begin_event_processing() try: diff --git a/lib/crewai/src/crewai/events/utils/console_formatter.py b/lib/crewai/src/crewai/events/utils/console_formatter.py index 0984406e9..7879a4d93 100644 --- a/lib/crewai/src/crewai/events/utils/console_formatter.py +++ b/lib/crewai/src/crewai/events/utils/console_formatter.py @@ -127,6 +127,9 @@ To update, run: uv sync --upgrade-package crewai""" def _show_tracing_disabled_message_if_needed(self) -> None: """Show tracing disabled message if tracing is not enabled.""" + from crewai.events.listeners.tracing.trace_listener import ( + TraceCollectionListener, + ) from crewai.events.listeners.tracing.utils import ( has_user_declined_tracing, is_tracing_enabled_in_context, @@ -136,6 +139,12 @@ To update, run: uv sync --upgrade-package crewai""" if should_suppress_tracing_messages(): return + # Don't show "disabled" message when the first-time handler will show + # the trace prompt after execution completes (avoids confusing mid-flow messages) + listener = TraceCollectionListener._instance # type: ignore[misc] + if listener and listener.first_time_handler.is_first_time: + return + if not is_tracing_enabled_in_context(): if has_user_declined_tracing(): message = """Info: Tracing is disabled. diff --git a/lib/crewai/tests/tracing/test_tracing.py b/lib/crewai/tests/tracing/test_tracing.py index c2558c17c..92f6e31c5 100644 --- a/lib/crewai/tests/tracing/test_tracing.py +++ b/lib/crewai/tests/tracing/test_tracing.py @@ -7,6 +7,7 @@ from crewai.events.listeners.tracing.first_time_trace_handler import ( FirstTimeTraceHandler, ) from crewai.events.listeners.tracing.trace_batch_manager import ( + TraceBatch, TraceBatchManager, ) from crewai.events.listeners.tracing.trace_listener import ( @@ -657,6 +658,16 @@ class TestTraceListenerSetup: trace_listener.first_time_handler.collected_events = True + mock_batch_response = MagicMock() + mock_batch_response.status_code = 201 + mock_batch_response.json.return_value = { + "trace_id": "mock-trace-id", + "ephemeral_trace_id": "mock-ephemeral-trace-id", + "access_code": "TRACE-mock", + } + mock_events_response = MagicMock() + mock_events_response.status_code = 200 + with ( patch.object( trace_listener.first_time_handler, @@ -666,6 +677,40 @@ class TestTraceListenerSetup: patch.object( trace_listener.first_time_handler, "_display_ephemeral_trace_link" ) as mock_display_link, + patch.object( + trace_listener.batch_manager.plus_api, + "initialize_trace_batch", + return_value=mock_batch_response, + ), + patch.object( + trace_listener.batch_manager.plus_api, + "initialize_ephemeral_trace_batch", + return_value=mock_batch_response, + ), + patch.object( + trace_listener.batch_manager.plus_api, + "send_trace_events", + return_value=mock_events_response, + ), + patch.object( + trace_listener.batch_manager.plus_api, + "send_ephemeral_trace_events", + return_value=mock_events_response, + ), + patch.object( + trace_listener.batch_manager.plus_api, + "finalize_trace_batch", + return_value=mock_events_response, + ), + patch.object( + trace_listener.batch_manager.plus_api, + "finalize_ephemeral_trace_batch", + return_value=mock_events_response, + ), + patch.object( + trace_listener.batch_manager, + "_cleanup_batch_data", + ), ): crew.kickoff() wait_for_event_handlers() @@ -918,3 +963,676 @@ class TestTraceListenerSetup: mock_init.assert_called_once() payload = mock_init.call_args[0][0] assert "user_identifier" not in payload + + +class TestTraceBatchIdClearedOnFailure: + """Tests: trace_batch_id is cleared when _initialize_backend_batch fails.""" + + def _make_batch_manager(self): + """Create a TraceBatchManager with a pre-set trace_batch_id (simulating first-time user).""" + with patch( + "crewai.events.listeners.tracing.trace_batch_manager.get_auth_token", + return_value="mock_token", + ): + bm = TraceBatchManager() + bm.current_batch = TraceBatch( + user_context={"privacy_level": "standard"}, + execution_metadata={"execution_type": "crew", "crew_name": "test"}, + ) + bm.trace_batch_id = bm.current_batch.batch_id # simulate line 96 + bm.is_current_batch_ephemeral = True + return bm + + def test_trace_batch_id_cleared_on_exception(self): + """trace_batch_id must be None when the API call raises an exception.""" + bm = self._make_batch_manager() + assert bm.trace_batch_id is not None + + with ( + patch( + "crewai.events.listeners.tracing.trace_batch_manager.is_tracing_enabled_in_context", + return_value=True, + ), + patch.object( + bm.plus_api, + "initialize_ephemeral_trace_batch", + side_effect=ConnectionError("network down"), + ), + ): + bm._initialize_backend_batch( + user_context={"privacy_level": "standard"}, + execution_metadata={"execution_type": "crew"}, + use_ephemeral=True, + ) + + assert bm.trace_batch_id is None + + def test_trace_batch_id_set_on_success(self): + """trace_batch_id must be set from the server response on success.""" + bm = self._make_batch_manager() + server_id = "server-ephemeral-trace-id-999" + + mock_response = MagicMock( + status_code=201, + json=MagicMock(return_value={"ephemeral_trace_id": server_id}), + ) + + with ( + patch( + "crewai.events.listeners.tracing.trace_batch_manager.is_tracing_enabled_in_context", + return_value=True, + ), + patch.object( + bm.plus_api, + "initialize_ephemeral_trace_batch", + return_value=mock_response, + ), + ): + bm._initialize_backend_batch( + user_context={"privacy_level": "standard"}, + execution_metadata={"execution_type": "crew"}, + use_ephemeral=True, + ) + + assert bm.trace_batch_id == server_id + + def test_send_events_skipped_when_trace_batch_id_none(self): + """_send_events_to_backend must return early when trace_batch_id is None.""" + bm = self._make_batch_manager() + bm.trace_batch_id = None + bm.event_buffer = [MagicMock()] # has events + + with patch.object( + bm.plus_api, "send_ephemeral_trace_events" + ) as mock_send: + result = bm._send_events_to_backend() + + assert result == 500 + mock_send.assert_not_called() + + +class TestInitializeBackendBatchRetry: + """Tests for retry logic in _initialize_backend_batch.""" + + def _make_batch_manager(self): + """Create a TraceBatchManager with a pre-set trace_batch_id.""" + with patch( + "crewai.events.listeners.tracing.trace_batch_manager.get_auth_token", + return_value="mock_token", + ): + bm = TraceBatchManager() + bm.current_batch = TraceBatch( + user_context={"privacy_level": "standard"}, + execution_metadata={"execution_type": "crew", "crew_name": "test"}, + ) + bm.trace_batch_id = bm.current_batch.batch_id + bm.is_current_batch_ephemeral = True + return bm + + def test_retries_on_none_response_then_succeeds(self): + """Retries when API returns None, succeeds on second attempt.""" + bm = self._make_batch_manager() + server_id = "server-id-after-retry" + + success_response = MagicMock( + status_code=201, + json=MagicMock(return_value={"ephemeral_trace_id": server_id}), + ) + + with ( + patch( + "crewai.events.listeners.tracing.trace_batch_manager.is_tracing_enabled_in_context", + return_value=True, + ), + patch.object( + bm.plus_api, + "initialize_ephemeral_trace_batch", + side_effect=[None, success_response], + ) as mock_init, + patch("crewai.events.listeners.tracing.trace_batch_manager.time.sleep") as mock_sleep, + ): + bm._initialize_backend_batch( + user_context={"privacy_level": "standard"}, + execution_metadata={"execution_type": "crew"}, + use_ephemeral=True, + ) + + assert bm.trace_batch_id == server_id + assert mock_init.call_count == 2 + mock_sleep.assert_called_once_with(0.2) + + def test_retries_on_5xx_then_succeeds(self): + """Retries on 500 server error, succeeds on second attempt.""" + bm = self._make_batch_manager() + server_id = "server-id-after-5xx" + + error_response = MagicMock(status_code=500, text="Internal Server Error") + success_response = MagicMock( + status_code=201, + json=MagicMock(return_value={"ephemeral_trace_id": server_id}), + ) + + with ( + patch( + "crewai.events.listeners.tracing.trace_batch_manager.is_tracing_enabled_in_context", + return_value=True, + ), + patch.object( + bm.plus_api, + "initialize_ephemeral_trace_batch", + side_effect=[error_response, success_response], + ) as mock_init, + patch("crewai.events.listeners.tracing.trace_batch_manager.time.sleep"), + ): + bm._initialize_backend_batch( + user_context={"privacy_level": "standard"}, + execution_metadata={"execution_type": "crew"}, + use_ephemeral=True, + ) + + assert bm.trace_batch_id == server_id + assert mock_init.call_count == 2 + + def test_no_retry_on_exception(self): + """Exceptions (e.g. timeout, connection error) abort immediately without retry.""" + bm = self._make_batch_manager() + + with ( + patch( + "crewai.events.listeners.tracing.trace_batch_manager.is_tracing_enabled_in_context", + return_value=True, + ), + patch.object( + bm.plus_api, + "initialize_ephemeral_trace_batch", + side_effect=ConnectionError("network down"), + ) as mock_init, + patch("crewai.events.listeners.tracing.trace_batch_manager.time.sleep") as mock_sleep, + ): + bm._initialize_backend_batch( + user_context={"privacy_level": "standard"}, + execution_metadata={"execution_type": "crew"}, + use_ephemeral=True, + ) + + assert bm.trace_batch_id is None + assert mock_init.call_count == 1 + mock_sleep.assert_not_called() + + def test_no_retry_on_4xx(self): + """Does NOT retry on 422 — client error is not transient.""" + bm = self._make_batch_manager() + + error_response = MagicMock(status_code=422, text="Unprocessable Entity") + + with ( + patch( + "crewai.events.listeners.tracing.trace_batch_manager.is_tracing_enabled_in_context", + return_value=True, + ), + patch.object( + bm.plus_api, + "initialize_ephemeral_trace_batch", + return_value=error_response, + ) as mock_init, + patch("crewai.events.listeners.tracing.trace_batch_manager.time.sleep") as mock_sleep, + ): + bm._initialize_backend_batch( + user_context={"privacy_level": "standard"}, + execution_metadata={"execution_type": "crew"}, + use_ephemeral=True, + ) + + assert bm.trace_batch_id is None + assert mock_init.call_count == 1 + mock_sleep.assert_not_called() + + def test_exhausts_retries_then_clears_batch_id(self): + """After all retries fail, trace_batch_id is None.""" + bm = self._make_batch_manager() + + with ( + patch( + "crewai.events.listeners.tracing.trace_batch_manager.is_tracing_enabled_in_context", + return_value=True, + ), + patch.object( + bm.plus_api, + "initialize_ephemeral_trace_batch", + return_value=None, + ) as mock_init, + patch("crewai.events.listeners.tracing.trace_batch_manager.time.sleep"), + ): + bm._initialize_backend_batch( + user_context={"privacy_level": "standard"}, + execution_metadata={"execution_type": "crew"}, + use_ephemeral=True, + ) + + assert bm.trace_batch_id is None + assert mock_init.call_count == 2 # initial + 1 retry + + +class TestFirstTimeHandlerBackendInitGuard: + """Tests: backend_initialized gated on actual batch creation success.""" + + def _make_handler_with_manager(self): + """Create a FirstTimeTraceHandler wired to a TraceBatchManager.""" + with patch( + "crewai.events.listeners.tracing.trace_batch_manager.get_auth_token", + return_value="mock_token", + ): + bm = TraceBatchManager() + bm.current_batch = TraceBatch( + user_context={"privacy_level": "standard"}, + execution_metadata={"execution_type": "crew", "crew_name": "test"}, + ) + bm.trace_batch_id = bm.current_batch.batch_id + bm.is_current_batch_ephemeral = True + + handler = FirstTimeTraceHandler() + handler.is_first_time = True + handler.collected_events = True + handler.batch_manager = bm + return handler, bm + + def test_backend_initialized_true_on_success(self): + """Events are sent when batch creation succeeds, then state is cleaned up.""" + handler, bm = self._make_handler_with_manager() + server_id = "server-id-abc" + + mock_init_response = MagicMock( + status_code=201, + json=MagicMock(return_value={"ephemeral_trace_id": server_id}), + ) + mock_send_response = MagicMock(status_code=200) + + trace_batch_id_during_send = None + + def capture_send(*args, **kwargs): + nonlocal trace_batch_id_during_send + trace_batch_id_during_send = bm.trace_batch_id + return mock_send_response + + with ( + patch( + "crewai.events.listeners.tracing.trace_batch_manager.is_tracing_enabled_in_context", + return_value=True, + ), + patch.object( + bm.plus_api, + "initialize_ephemeral_trace_batch", + return_value=mock_init_response, + ), + patch.object( + bm.plus_api, + "send_ephemeral_trace_events", + side_effect=capture_send, + ), + patch.object(bm, "_finalize_backend_batch"), + ): + bm.event_buffer = [MagicMock(to_dict=MagicMock(return_value={}))] + handler._initialize_backend_and_send_events() + + # trace_batch_id was set correctly during send + assert trace_batch_id_during_send == server_id + # State cleaned up after completion (singleton reuse) + assert bm.backend_initialized is False + assert bm.trace_batch_id is None + assert bm.current_batch is None + + def test_backend_initialized_false_on_failure(self): + """backend_initialized stays False and events are NOT sent when batch creation fails.""" + handler, bm = self._make_handler_with_manager() + + with ( + patch( + "crewai.events.listeners.tracing.trace_batch_manager.is_tracing_enabled_in_context", + return_value=True, + ), + patch.object( + bm.plus_api, + "initialize_ephemeral_trace_batch", + return_value=None, # server call fails + ), + patch.object(bm, "_send_events_to_backend") as mock_send, + patch.object(bm, "_finalize_backend_batch") as mock_finalize, + patch.object(handler, "_gracefully_fail") as mock_fail, + ): + bm.event_buffer = [MagicMock()] + handler._initialize_backend_and_send_events() + + assert bm.backend_initialized is False + assert bm.trace_batch_id is None + mock_send.assert_not_called() + mock_finalize.assert_not_called() + mock_fail.assert_called_once() + + def test_backend_initialized_false_on_non_2xx(self): + """backend_initialized stays False when server returns non-2xx.""" + handler, bm = self._make_handler_with_manager() + + mock_response = MagicMock(status_code=500, text="Internal Server Error") + + with ( + patch( + "crewai.events.listeners.tracing.trace_batch_manager.is_tracing_enabled_in_context", + return_value=True, + ), + patch.object( + bm.plus_api, + "initialize_ephemeral_trace_batch", + return_value=mock_response, + ), + patch.object(bm, "_send_events_to_backend") as mock_send, + patch.object(bm, "_finalize_backend_batch") as mock_finalize, + patch.object(handler, "_gracefully_fail") as mock_fail, + ): + bm.event_buffer = [MagicMock()] + handler._initialize_backend_and_send_events() + + assert bm.backend_initialized is False + assert bm.trace_batch_id is None + mock_send.assert_not_called() + mock_finalize.assert_not_called() + mock_fail.assert_called_once() + + +class TestFirstTimeHandlerAlwaysEphemeral: + """Tests that first-time handler always uses ephemeral with skip_context_check.""" + + def _make_handler_with_manager(self): + with patch( + "crewai.events.listeners.tracing.trace_batch_manager.get_auth_token", + return_value="mock_token", + ): + bm = TraceBatchManager() + bm.current_batch = TraceBatch( + user_context={"privacy_level": "standard"}, + execution_metadata={"execution_type": "crew", "crew_name": "test"}, + ) + bm.trace_batch_id = bm.current_batch.batch_id + bm.is_current_batch_ephemeral = True + + handler = FirstTimeTraceHandler() + handler.is_first_time = True + handler.collected_events = True + handler.batch_manager = bm + return handler, bm + + def test_deferred_init_uses_ephemeral_and_skip_context_check(self): + """Deferred backend init always uses ephemeral=True and skip_context_check=True.""" + handler, bm = self._make_handler_with_manager() + + with ( + patch.object(bm, "_initialize_backend_batch") as mock_init, + patch.object(bm, "_send_events_to_backend"), + patch.object(bm, "_finalize_backend_batch"), + ): + mock_init.side_effect = lambda **kwargs: None + bm.event_buffer = [MagicMock()] + handler._initialize_backend_and_send_events() + + mock_init.assert_called_once() + assert mock_init.call_args.kwargs["use_ephemeral"] is True + assert mock_init.call_args.kwargs["skip_context_check"] is True + + +class TestAuthFailbackToEphemeral: + """Tests for ephemeral fallback when server rejects auth (401/403).""" + + def _make_batch_manager(self): + """Create a TraceBatchManager with a pre-set trace_batch_id.""" + with patch( + "crewai.events.listeners.tracing.trace_batch_manager.get_auth_token", + return_value="mock_token", + ): + bm = TraceBatchManager() + bm.current_batch = TraceBatch( + user_context={"privacy_level": "standard"}, + execution_metadata={"execution_type": "crew", "crew_name": "test"}, + ) + bm.trace_batch_id = bm.current_batch.batch_id + bm.is_current_batch_ephemeral = False # authenticated path + return bm + + def test_401_non_ephemeral_falls_back_to_ephemeral(self): + """A 401 on the non-ephemeral endpoint should retry as ephemeral.""" + bm = self._make_batch_manager() + server_id = "ephemeral-fallback-id" + + auth_rejected = MagicMock(status_code=401, text="Bad credentials") + ephemeral_success = MagicMock( + status_code=201, + json=MagicMock(return_value={"ephemeral_trace_id": server_id}), + ) + + with ( + patch( + "crewai.events.listeners.tracing.trace_batch_manager.is_tracing_enabled_in_context", + return_value=True, + ), + patch.object( + bm.plus_api, + "initialize_trace_batch", + return_value=auth_rejected, + ), + patch.object( + bm.plus_api, + "initialize_ephemeral_trace_batch", + return_value=ephemeral_success, + ) as mock_ephemeral, + patch("crewai.events.listeners.tracing.trace_batch_manager.time.sleep"), + ): + bm._initialize_backend_batch( + user_context={"privacy_level": "standard"}, + execution_metadata={"execution_type": "crew"}, + use_ephemeral=False, + ) + + assert bm.trace_batch_id == server_id + assert bm.is_current_batch_ephemeral is True + mock_ephemeral.assert_called_once() + + def test_403_non_ephemeral_falls_back_to_ephemeral(self): + """A 403 on the non-ephemeral endpoint should also fall back.""" + bm = self._make_batch_manager() + server_id = "ephemeral-fallback-403" + + forbidden = MagicMock(status_code=403, text="Forbidden") + ephemeral_success = MagicMock( + status_code=201, + json=MagicMock(return_value={"ephemeral_trace_id": server_id}), + ) + + with ( + patch( + "crewai.events.listeners.tracing.trace_batch_manager.is_tracing_enabled_in_context", + return_value=True, + ), + patch.object( + bm.plus_api, + "initialize_trace_batch", + return_value=forbidden, + ), + patch.object( + bm.plus_api, + "initialize_ephemeral_trace_batch", + return_value=ephemeral_success, + ), + patch("crewai.events.listeners.tracing.trace_batch_manager.time.sleep"), + ): + bm._initialize_backend_batch( + user_context={"privacy_level": "standard"}, + execution_metadata={"execution_type": "crew"}, + use_ephemeral=False, + ) + + assert bm.trace_batch_id == server_id + assert bm.is_current_batch_ephemeral is True + + def test_401_on_ephemeral_does_not_recurse(self): + """A 401 on the ephemeral endpoint should NOT try to fall back again.""" + bm = self._make_batch_manager() + bm.is_current_batch_ephemeral = True + + auth_rejected = MagicMock(status_code=401, text="Bad credentials") + + with ( + patch( + "crewai.events.listeners.tracing.trace_batch_manager.is_tracing_enabled_in_context", + return_value=True, + ), + patch.object( + bm.plus_api, + "initialize_ephemeral_trace_batch", + return_value=auth_rejected, + ) as mock_ephemeral, + patch("crewai.events.listeners.tracing.trace_batch_manager.time.sleep"), + ): + bm._initialize_backend_batch( + user_context={"privacy_level": "standard"}, + execution_metadata={"execution_type": "crew"}, + use_ephemeral=True, + ) + + assert bm.trace_batch_id is None + # Called only once — no recursive fallback + mock_ephemeral.assert_called() + + def test_401_fallback_ephemeral_also_fails(self): + """If ephemeral fallback also fails, trace_batch_id is cleared.""" + bm = self._make_batch_manager() + + auth_rejected = MagicMock(status_code=401, text="Bad credentials") + ephemeral_fail = MagicMock(status_code=422, text="Validation failed") + + with ( + patch( + "crewai.events.listeners.tracing.trace_batch_manager.is_tracing_enabled_in_context", + return_value=True, + ), + patch.object( + bm.plus_api, + "initialize_trace_batch", + return_value=auth_rejected, + ), + patch.object( + bm.plus_api, + "initialize_ephemeral_trace_batch", + return_value=ephemeral_fail, + ), + patch("crewai.events.listeners.tracing.trace_batch_manager.time.sleep"), + ): + bm._initialize_backend_batch( + user_context={"privacy_level": "standard"}, + execution_metadata={"execution_type": "crew"}, + use_ephemeral=False, + ) + + assert bm.trace_batch_id is None + + +class TestMarkBatchAsFailedRouting: + """Tests: _mark_batch_as_failed routes to the correct endpoint.""" + + def _make_batch_manager(self, ephemeral: bool = False): + with patch( + "crewai.events.listeners.tracing.trace_batch_manager.get_auth_token", + return_value="mock_token", + ): + bm = TraceBatchManager() + bm.is_current_batch_ephemeral = ephemeral + return bm + + def test_routes_to_ephemeral_endpoint_when_ephemeral(self): + """Ephemeral batches must use mark_ephemeral_trace_batch_as_failed.""" + bm = self._make_batch_manager(ephemeral=True) + + with patch.object( + bm.plus_api, "mark_ephemeral_trace_batch_as_failed" + ) as mock_ephemeral, patch.object( + bm.plus_api, "mark_trace_batch_as_failed" + ) as mock_non_ephemeral: + bm._mark_batch_as_failed("batch-123", "some error") + + mock_ephemeral.assert_called_once_with("batch-123", "some error") + mock_non_ephemeral.assert_not_called() + + def test_routes_to_non_ephemeral_endpoint_when_not_ephemeral(self): + """Non-ephemeral batches must use mark_trace_batch_as_failed.""" + bm = self._make_batch_manager(ephemeral=False) + + with patch.object( + bm.plus_api, "mark_ephemeral_trace_batch_as_failed" + ) as mock_ephemeral, patch.object( + bm.plus_api, "mark_trace_batch_as_failed" + ) as mock_non_ephemeral: + bm._mark_batch_as_failed("batch-456", "another error") + + mock_non_ephemeral.assert_called_once_with("batch-456", "another error") + mock_ephemeral.assert_not_called() + + +class TestBackendInitializedGatedOnSuccess: + """Tests: backend_initialized reflects actual init success on non-first-time path.""" + + def test_backend_initialized_true_on_success(self): + """backend_initialized is True when _initialize_backend_batch succeeds.""" + with ( + patch( + "crewai.events.listeners.tracing.trace_batch_manager.is_tracing_enabled_in_context", + return_value=True, + ), + patch( + "crewai.events.listeners.tracing.trace_batch_manager.should_auto_collect_first_time_traces", + return_value=False, + ), + patch( + "crewai.events.listeners.tracing.trace_batch_manager.get_auth_token", + return_value="mock_token", + ), + ): + bm = TraceBatchManager() + mock_response = MagicMock( + status_code=201, + json=MagicMock(return_value={"trace_id": "server-id"}), + ) + with patch.object( + bm.plus_api, "initialize_trace_batch", return_value=mock_response + ): + bm.initialize_batch( + user_context={"privacy_level": "standard"}, + execution_metadata={"execution_type": "crew"}, + ) + + assert bm.backend_initialized is True + assert bm.trace_batch_id == "server-id" + + def test_backend_initialized_false_on_failure(self): + """backend_initialized is False when _initialize_backend_batch fails.""" + with ( + patch( + "crewai.events.listeners.tracing.trace_batch_manager.is_tracing_enabled_in_context", + return_value=True, + ), + patch( + "crewai.events.listeners.tracing.trace_batch_manager.should_auto_collect_first_time_traces", + return_value=False, + ), + patch( + "crewai.events.listeners.tracing.trace_batch_manager.get_auth_token", + return_value="mock_token", + ), + ): + bm = TraceBatchManager() + with patch.object( + bm.plus_api, "initialize_trace_batch", return_value=None + ): + bm.initialize_batch( + user_context={"privacy_level": "standard"}, + execution_metadata={"execution_type": "crew"}, + ) + + assert bm.backend_initialized is False + assert bm.trace_batch_id is None From 454156cff92815213d48d733c08a5a9adfa161e6 Mon Sep 17 00:00:00 2001 From: Greyson LaLonde Date: Thu, 26 Mar 2026 04:12:49 +0800 Subject: [PATCH 16/25] feat: bump versions to 1.12.0a3 --- lib/crewai-files/src/crewai_files/__init__.py | 2 +- lib/crewai-tools/pyproject.toml | 2 +- lib/crewai-tools/src/crewai_tools/__init__.py | 2 +- lib/crewai/pyproject.toml | 2 +- lib/crewai/src/crewai/__init__.py | 2 +- lib/crewai/src/crewai/cli/templates/crew/pyproject.toml | 2 +- lib/crewai/src/crewai/cli/templates/flow/pyproject.toml | 2 +- lib/crewai/src/crewai/cli/templates/tool/pyproject.toml | 2 +- lib/devtools/src/crewai_devtools/__init__.py | 2 +- 9 files changed, 9 insertions(+), 9 deletions(-) diff --git a/lib/crewai-files/src/crewai_files/__init__.py b/lib/crewai-files/src/crewai_files/__init__.py index 927232168..3ffc6c2c1 100644 --- a/lib/crewai-files/src/crewai_files/__init__.py +++ b/lib/crewai-files/src/crewai_files/__init__.py @@ -152,4 +152,4 @@ __all__ = [ "wrap_file_source", ] -__version__ = "1.12.0a2" +__version__ = "1.12.0a3" diff --git a/lib/crewai-tools/pyproject.toml b/lib/crewai-tools/pyproject.toml index 47ae3bebb..3c7ce1c7a 100644 --- a/lib/crewai-tools/pyproject.toml +++ b/lib/crewai-tools/pyproject.toml @@ -11,7 +11,7 @@ dependencies = [ "pytube~=15.0.0", "requests~=2.32.5", "docker~=7.1.0", - "crewai==1.12.0a2", + "crewai==1.12.0a3", "tiktoken~=0.8.0", "beautifulsoup4~=4.13.4", "python-docx~=1.2.0", diff --git a/lib/crewai-tools/src/crewai_tools/__init__.py b/lib/crewai-tools/src/crewai_tools/__init__.py index ea14bfc93..e76598202 100644 --- a/lib/crewai-tools/src/crewai_tools/__init__.py +++ b/lib/crewai-tools/src/crewai_tools/__init__.py @@ -309,4 +309,4 @@ __all__ = [ "ZapierActionTools", ] -__version__ = "1.12.0a2" +__version__ = "1.12.0a3" diff --git a/lib/crewai/pyproject.toml b/lib/crewai/pyproject.toml index cd3809b12..caeb6715c 100644 --- a/lib/crewai/pyproject.toml +++ b/lib/crewai/pyproject.toml @@ -54,7 +54,7 @@ Repository = "https://github.com/crewAIInc/crewAI" [project.optional-dependencies] tools = [ - "crewai-tools==1.12.0a2", + "crewai-tools==1.12.0a3", ] embeddings = [ "tiktoken~=0.8.0" diff --git a/lib/crewai/src/crewai/__init__.py b/lib/crewai/src/crewai/__init__.py index dcaa55f84..a2de5d174 100644 --- a/lib/crewai/src/crewai/__init__.py +++ b/lib/crewai/src/crewai/__init__.py @@ -42,7 +42,7 @@ def _suppress_pydantic_deprecation_warnings() -> None: _suppress_pydantic_deprecation_warnings() -__version__ = "1.12.0a2" +__version__ = "1.12.0a3" _telemetry_submitted = False diff --git a/lib/crewai/src/crewai/cli/templates/crew/pyproject.toml b/lib/crewai/src/crewai/cli/templates/crew/pyproject.toml index 8ecce0a71..0271a13fc 100644 --- a/lib/crewai/src/crewai/cli/templates/crew/pyproject.toml +++ b/lib/crewai/src/crewai/cli/templates/crew/pyproject.toml @@ -5,7 +5,7 @@ description = "{{name}} using crewAI" authors = [{ name = "Your Name", email = "you@example.com" }] requires-python = ">=3.10,<3.14" dependencies = [ - "crewai[tools]==1.12.0a2" + "crewai[tools]==1.12.0a3" ] [project.scripts] diff --git a/lib/crewai/src/crewai/cli/templates/flow/pyproject.toml b/lib/crewai/src/crewai/cli/templates/flow/pyproject.toml index c4d9b4452..b3cfd338e 100644 --- a/lib/crewai/src/crewai/cli/templates/flow/pyproject.toml +++ b/lib/crewai/src/crewai/cli/templates/flow/pyproject.toml @@ -5,7 +5,7 @@ description = "{{name}} using crewAI" authors = [{ name = "Your Name", email = "you@example.com" }] requires-python = ">=3.10,<3.14" dependencies = [ - "crewai[tools]==1.12.0a2" + "crewai[tools]==1.12.0a3" ] [project.scripts] diff --git a/lib/crewai/src/crewai/cli/templates/tool/pyproject.toml b/lib/crewai/src/crewai/cli/templates/tool/pyproject.toml index 3426991fc..9a549f520 100644 --- a/lib/crewai/src/crewai/cli/templates/tool/pyproject.toml +++ b/lib/crewai/src/crewai/cli/templates/tool/pyproject.toml @@ -5,7 +5,7 @@ description = "Power up your crews with {{folder_name}}" readme = "README.md" requires-python = ">=3.10,<3.14" dependencies = [ - "crewai[tools]==1.12.0a2" + "crewai[tools]==1.12.0a3" ] [tool.crewai] diff --git a/lib/devtools/src/crewai_devtools/__init__.py b/lib/devtools/src/crewai_devtools/__init__.py index b8ca3fb18..b28bb3afe 100644 --- a/lib/devtools/src/crewai_devtools/__init__.py +++ b/lib/devtools/src/crewai_devtools/__init__.py @@ -1,3 +1,3 @@ """CrewAI development tools.""" -__version__ = "1.12.0a2" +__version__ = "1.12.0a3" From b5a0d6e709b3466b2fd2c68a243499e24aaa4db8 Mon Sep 17 00:00:00 2001 From: Greyson LaLonde Date: Thu, 26 Mar 2026 04:17:37 +0800 Subject: [PATCH 17/25] docs: update changelog and version for v1.12.0a3 --- docs/ar/changelog.mdx | 20 ++++++++++++++++++++ docs/en/changelog.mdx | 20 ++++++++++++++++++++ docs/ko/changelog.mdx | 20 ++++++++++++++++++++ docs/pt-BR/changelog.mdx | 20 ++++++++++++++++++++ 4 files changed, 80 insertions(+) diff --git a/docs/ar/changelog.mdx b/docs/ar/changelog.mdx index c8bea9db8..7bea5df8f 100644 --- a/docs/ar/changelog.mdx +++ b/docs/ar/changelog.mdx @@ -4,6 +4,26 @@ description: "تحديثات المنتج والتحسينات وإصلاحات icon: "clock" mode: "wide" --- + + ## v1.12.0a3 + + [عرض الإصدار على GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.12.0a3) + + ## ما الذي تغير + + ### إصلاحات الأخطاء + - إصلاح بيانات الاعتماد الخاطئة لدفع دفعات التتبع (404) + - حل العديد من الأخطاء في نظام تدفق HITL + + ### الوثائق + - تحديث سجل التغييرات والإصدار لـ v1.12.0a2 + + ## المساهمون + + @akaKuruma, @greysonlalonde + + + ## v1.12.0a2 diff --git a/docs/en/changelog.mdx b/docs/en/changelog.mdx index 109b0bed6..23b863e94 100644 --- a/docs/en/changelog.mdx +++ b/docs/en/changelog.mdx @@ -4,6 +4,26 @@ description: "Product updates, improvements, and bug fixes for CrewAI" icon: "clock" mode: "wide" --- + + ## v1.12.0a3 + + [View release on GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.12.0a3) + + ## What's Changed + + ### Bug Fixes + - Fix bad credentials for traces batch push (404) + - Resolve multiple bugs in HITL flow system + + ### Documentation + - Update changelog and version for v1.12.0a2 + + ## Contributors + + @akaKuruma, @greysonlalonde + + + ## v1.12.0a2 diff --git a/docs/ko/changelog.mdx b/docs/ko/changelog.mdx index 3e3e4a482..12efce93e 100644 --- a/docs/ko/changelog.mdx +++ b/docs/ko/changelog.mdx @@ -4,6 +4,26 @@ description: "CrewAI의 제품 업데이트, 개선 사항 및 버그 수정" icon: "clock" mode: "wide" --- + + ## v1.12.0a3 + + [GitHub 릴리스 보기](https://github.com/crewAIInc/crewAI/releases/tag/1.12.0a3) + + ## 변경 사항 + + ### 버그 수정 + - 트레이스 배치 푸시에 대한 잘못된 자격 증명 수정 (404) + - HITL 흐름 시스템의 여러 버그 해결 + + ### 문서 + - v1.12.0a2에 대한 변경 로그 및 버전 업데이트 + + ## 기여자 + + @akaKuruma, @greysonlalonde + + + ## v1.12.0a2 diff --git a/docs/pt-BR/changelog.mdx b/docs/pt-BR/changelog.mdx index fb44d9f04..fd77840a8 100644 --- a/docs/pt-BR/changelog.mdx +++ b/docs/pt-BR/changelog.mdx @@ -4,6 +4,26 @@ description: "Atualizações de produto, melhorias e correções do CrewAI" icon: "clock" mode: "wide" --- + + ## v1.12.0a3 + + [Ver release no GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.12.0a3) + + ## O que Mudou + + ### Correções de Bugs + - Corrigir credenciais inválidas para envio em lote de rastros (404) + - Resolver múltiplos bugs no sistema de fluxo HITL + + ### Documentação + - Atualizar changelog e versão para v1.12.0a2 + + ## Contributors + + @akaKuruma, @greysonlalonde + + + ## v1.12.0a2 From c183b77991f1e25b6e399f8e21cc855f80674c7f Mon Sep 17 00:00:00 2001 From: alex-clawd Date: Wed, 25 Mar 2026 14:22:13 -0700 Subject: [PATCH 18/25] fix: address Copilot review on OpenAI-compatible providers (#5042) (#5089) - Delegate supports_function_calling() to parent (handles o1 models via OpenRouter) - Guard empty env vars in base_url resolution - Fix misleading comment about model validation rules - Remove unused MagicMock import - Use 'is not None' for env var restoration in tests Co-authored-by: Joao Moura --- lib/crewai/src/crewai/llm.py | 4 ++-- .../llms/providers/openai_compatible/completion.py | 11 +++++++---- .../llms/openai_compatible/test_openai_compatible.py | 4 ++-- 3 files changed, 11 insertions(+), 8 deletions(-) diff --git a/lib/crewai/src/crewai/llm.py b/lib/crewai/src/crewai/llm.py index 0b3b158d6..75b1f6546 100644 --- a/lib/crewai/src/crewai/llm.py +++ b/lib/crewai/src/crewai/llm.py @@ -483,8 +483,8 @@ class LLM(BaseLLM): for prefix in ["gpt-", "gpt-35-", "o1", "o3", "o4", "azure-"] ) - # OpenAI-compatible providers - accept any model name since these - # providers host many different models with varied naming conventions + # OpenAI-compatible providers - most accept any model name, but some + # (DeepSeek, Dashscope) restrict to their own model prefixes if provider == "deepseek": return model_lower.startswith("deepseek") diff --git a/lib/crewai/src/crewai/llms/providers/openai_compatible/completion.py b/lib/crewai/src/crewai/llms/providers/openai_compatible/completion.py index 9c308f52e..293e73ff0 100644 --- a/lib/crewai/src/crewai/llms/providers/openai_compatible/completion.py +++ b/lib/crewai/src/crewai/llms/providers/openai_compatible/completion.py @@ -239,7 +239,8 @@ class OpenAICompatibleCompletion(OpenAICompletion): if base_url: resolved = base_url elif config.base_url_env: - resolved = os.getenv(config.base_url_env, config.base_url) + env_value = os.getenv(config.base_url_env) + resolved = env_value if env_value else config.base_url else: resolved = config.base_url @@ -274,9 +275,11 @@ class OpenAICompatibleCompletion(OpenAICompletion): def supports_function_calling(self) -> bool: """Check if the provider supports function calling. - All modern OpenAI-compatible providers support function calling. + Delegates to the parent OpenAI implementation which handles + edge cases like o1 models (which may be routed through + OpenRouter or other compatible providers). Returns: - True, as all supported providers have function calling support. + Whether the model supports function calling. """ - return True + return super().supports_function_calling() diff --git a/lib/crewai/tests/llms/openai_compatible/test_openai_compatible.py b/lib/crewai/tests/llms/openai_compatible/test_openai_compatible.py index ade54fb8c..fd5970299 100644 --- a/lib/crewai/tests/llms/openai_compatible/test_openai_compatible.py +++ b/lib/crewai/tests/llms/openai_compatible/test_openai_compatible.py @@ -1,7 +1,7 @@ """Tests for OpenAI-compatible providers.""" import os -from unittest.mock import MagicMock, patch +from unittest.mock import patch import pytest @@ -133,7 +133,7 @@ class TestOpenAICompatibleCompletion: with pytest.raises(ValueError, match="API key required"): OpenAICompatibleCompletion(model="deepseek-chat", provider="deepseek") finally: - if original: + if original is not None: os.environ[env_key] = original def test_api_key_from_env(self): From 6fd70ce6e5b4aef4956a1517a209ce049ecc8f31 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jo=C3=A3o=20Moura?= Date: Wed, 25 Mar 2026 18:03:37 -0700 Subject: [PATCH 19/25] chore: bump version to 1.14.0 across all modules (#5090) * chore: bump version to 1.14.0 across all modules * chore: downgrade version to 1.12.0 across all modules --- lib/crewai-files/src/crewai_files/__init__.py | 2 +- lib/crewai-tools/src/crewai_tools/__init__.py | 2 +- lib/crewai/src/crewai/__init__.py | 2 +- lib/devtools/src/crewai_devtools/__init__.py | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/lib/crewai-files/src/crewai_files/__init__.py b/lib/crewai-files/src/crewai_files/__init__.py index 3ffc6c2c1..15f3af21f 100644 --- a/lib/crewai-files/src/crewai_files/__init__.py +++ b/lib/crewai-files/src/crewai_files/__init__.py @@ -152,4 +152,4 @@ __all__ = [ "wrap_file_source", ] -__version__ = "1.12.0a3" +__version__ = "1.12.0" diff --git a/lib/crewai-tools/src/crewai_tools/__init__.py b/lib/crewai-tools/src/crewai_tools/__init__.py index e76598202..d2850a8b8 100644 --- a/lib/crewai-tools/src/crewai_tools/__init__.py +++ b/lib/crewai-tools/src/crewai_tools/__init__.py @@ -309,4 +309,4 @@ __all__ = [ "ZapierActionTools", ] -__version__ = "1.12.0a3" +__version__ = "1.12.0" diff --git a/lib/crewai/src/crewai/__init__.py b/lib/crewai/src/crewai/__init__.py index a2de5d174..f352b84e2 100644 --- a/lib/crewai/src/crewai/__init__.py +++ b/lib/crewai/src/crewai/__init__.py @@ -42,7 +42,7 @@ def _suppress_pydantic_deprecation_warnings() -> None: _suppress_pydantic_deprecation_warnings() -__version__ = "1.12.0a3" +__version__ = "1.12.0" _telemetry_submitted = False diff --git a/lib/devtools/src/crewai_devtools/__init__.py b/lib/devtools/src/crewai_devtools/__init__.py index b28bb3afe..ac5ed2ca5 100644 --- a/lib/devtools/src/crewai_devtools/__init__.py +++ b/lib/devtools/src/crewai_devtools/__init__.py @@ -1,3 +1,3 @@ """CrewAI development tools.""" -__version__ = "1.12.0a3" +__version__ = "1.12.0" From 371e6cfd11cb5c0d31fa4605a1c0018b6c0019bc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jo=C3=A3o=20Moura?= Date: Wed, 25 Mar 2026 18:07:28 -0700 Subject: [PATCH 20/25] docs: update changelog and version for v1.12.0 (#5091) --- docs/ar/changelog.mdx | 45 + docs/docs.json | 1863 +++++++++++++++++++++++++++++++++++++- docs/en/changelog.mdx | 45 + docs/ko/changelog.mdx | 45 + docs/pt-BR/changelog.mdx | 45 + 5 files changed, 2039 insertions(+), 4 deletions(-) diff --git a/docs/ar/changelog.mdx b/docs/ar/changelog.mdx index 7bea5df8f..6137596f0 100644 --- a/docs/ar/changelog.mdx +++ b/docs/ar/changelog.mdx @@ -4,6 +4,51 @@ description: "تحديثات المنتج والتحسينات وإصلاحات icon: "clock" mode: "wide" --- + + ## 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 diff --git a/docs/docs.json b/docs/docs.json index bb9750bd8..7f1e03e37 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -56,7 +56,7 @@ }, "versions": [ { - "version": "v1.11.1", + "version": "v1.12.0", "default": true, "tabs": [ { @@ -525,6 +525,475 @@ } ] }, + { + "version": "v1.11.1", + "tabs": [ + { + "tab": "Home", + "icon": "house", + "groups": [ + { + "group": "Welcome", + "pages": [ + "index" + ] + } + ] + }, + { + "tab": "Documentation", + "icon": "book-open", + "groups": [ + { + "group": "Get Started", + "pages": [ + "en/introduction", + "en/installation", + "en/quickstart" + ] + }, + { + "group": "Guides", + "pages": [ + { + "group": "Strategy", + "icon": "compass", + "pages": [ + "en/guides/concepts/evaluating-use-cases" + ] + }, + { + "group": "Agents", + "icon": "user", + "pages": [ + "en/guides/agents/crafting-effective-agents" + ] + }, + { + "group": "Crews", + "icon": "users", + "pages": [ + "en/guides/crews/first-crew" + ] + }, + { + "group": "Flows", + "icon": "code-branch", + "pages": [ + "en/guides/flows/first-flow", + "en/guides/flows/mastering-flow-state" + ] + }, + { + "group": "Tools", + "icon": "wrench", + "pages": [ + "en/guides/tools/publish-custom-tools" + ] + }, + { + "group": "Coding Tools", + "icon": "terminal", + "pages": [ + "en/guides/coding-tools/agents-md" + ] + }, + { + "group": "Advanced", + "icon": "gear", + "pages": [ + "en/guides/advanced/customizing-prompts", + "en/guides/advanced/fingerprinting" + ] + }, + { + "group": "Migration", + "icon": "shuffle", + "pages": [ + "en/guides/migration/migrating-from-langgraph" + ] + } + ] + }, + { + "group": "Core Concepts", + "pages": [ + "en/concepts/agents", + "en/concepts/tasks", + "en/concepts/crews", + "en/concepts/flows", + "en/concepts/production-architecture", + "en/concepts/knowledge", + "en/concepts/skills", + "en/concepts/llms", + "en/concepts/files", + "en/concepts/processes", + "en/concepts/collaboration", + "en/concepts/training", + "en/concepts/memory", + "en/concepts/reasoning", + "en/concepts/planning", + "en/concepts/testing", + "en/concepts/cli", + "en/concepts/tools", + "en/concepts/event-listener" + ] + }, + { + "group": "MCP Integration", + "pages": [ + "en/mcp/overview", + "en/mcp/dsl-integration", + "en/mcp/stdio", + "en/mcp/sse", + "en/mcp/streamable-http", + "en/mcp/multiple-servers", + "en/mcp/security" + ] + }, + { + "group": "Tools", + "pages": [ + "en/tools/overview", + { + "group": "File & Document", + "icon": "folder-open", + "pages": [ + "en/tools/file-document/overview", + "en/tools/file-document/filereadtool", + "en/tools/file-document/filewritetool", + "en/tools/file-document/pdfsearchtool", + "en/tools/file-document/docxsearchtool", + "en/tools/file-document/mdxsearchtool", + "en/tools/file-document/xmlsearchtool", + "en/tools/file-document/txtsearchtool", + "en/tools/file-document/jsonsearchtool", + "en/tools/file-document/csvsearchtool", + "en/tools/file-document/directorysearchtool", + "en/tools/file-document/directoryreadtool", + "en/tools/file-document/ocrtool", + "en/tools/file-document/pdf-text-writing-tool" + ] + }, + { + "group": "Web Scraping & Browsing", + "icon": "globe", + "pages": [ + "en/tools/web-scraping/overview", + "en/tools/web-scraping/scrapewebsitetool", + "en/tools/web-scraping/scrapeelementfromwebsitetool", + "en/tools/web-scraping/scrapflyscrapetool", + "en/tools/web-scraping/seleniumscrapingtool", + "en/tools/web-scraping/scrapegraphscrapetool", + "en/tools/web-scraping/spidertool", + "en/tools/web-scraping/browserbaseloadtool", + "en/tools/web-scraping/hyperbrowserloadtool", + "en/tools/web-scraping/stagehandtool", + "en/tools/web-scraping/firecrawlcrawlwebsitetool", + "en/tools/web-scraping/firecrawlscrapewebsitetool", + "en/tools/web-scraping/oxylabsscraperstool", + "en/tools/web-scraping/brightdata-tools" + ] + }, + { + "group": "Search & Research", + "icon": "magnifying-glass", + "pages": [ + "en/tools/search-research/overview", + "en/tools/search-research/serperdevtool", + "en/tools/search-research/bravesearchtool", + "en/tools/search-research/exasearchtool", + "en/tools/search-research/linkupsearchtool", + "en/tools/search-research/githubsearchtool", + "en/tools/search-research/websitesearchtool", + "en/tools/search-research/codedocssearchtool", + "en/tools/search-research/youtubechannelsearchtool", + "en/tools/search-research/youtubevideosearchtool", + "en/tools/search-research/tavilysearchtool", + "en/tools/search-research/tavilyextractortool", + "en/tools/search-research/arxivpapertool", + "en/tools/search-research/serpapi-googlesearchtool", + "en/tools/search-research/serpapi-googleshoppingtool", + "en/tools/search-research/databricks-query-tool" + ] + }, + { + "group": "Database & Data", + "icon": "database", + "pages": [ + "en/tools/database-data/overview", + "en/tools/database-data/mysqltool", + "en/tools/database-data/pgsearchtool", + "en/tools/database-data/snowflakesearchtool", + "en/tools/database-data/nl2sqltool", + "en/tools/database-data/qdrantvectorsearchtool", + "en/tools/database-data/weaviatevectorsearchtool", + "en/tools/database-data/mongodbvectorsearchtool", + "en/tools/database-data/singlestoresearchtool" + ] + }, + { + "group": "AI & Machine Learning", + "icon": "brain", + "pages": [ + "en/tools/ai-ml/overview", + "en/tools/ai-ml/dalletool", + "en/tools/ai-ml/visiontool", + "en/tools/ai-ml/aimindtool", + "en/tools/ai-ml/llamaindextool", + "en/tools/ai-ml/langchaintool", + "en/tools/ai-ml/ragtool", + "en/tools/ai-ml/codeinterpretertool" + ] + }, + { + "group": "Cloud & Storage", + "icon": "cloud", + "pages": [ + "en/tools/cloud-storage/overview", + "en/tools/cloud-storage/s3readertool", + "en/tools/cloud-storage/s3writertool", + "en/tools/cloud-storage/bedrockkbretriever" + ] + }, + { + "group": "Integrations", + "icon": "plug", + "pages": [ + "en/tools/integration/overview", + "en/tools/integration/bedrockinvokeagenttool", + "en/tools/integration/crewaiautomationtool", + "en/tools/integration/mergeagenthandlertool" + ] + }, + { + "group": "Automation", + "icon": "bolt", + "pages": [ + "en/tools/automation/overview", + "en/tools/automation/apifyactorstool", + "en/tools/automation/composiotool", + "en/tools/automation/multiontool", + "en/tools/automation/zapieractionstool" + ] + } + ] + }, + { + "group": "Observability", + "pages": [ + "en/observability/tracing", + "en/observability/overview", + "en/observability/arize-phoenix", + "en/observability/braintrust", + "en/observability/datadog", + "en/observability/galileo", + "en/observability/langdb", + "en/observability/langfuse", + "en/observability/langtrace", + "en/observability/maxim", + "en/observability/mlflow", + "en/observability/neatlogs", + "en/observability/openlit", + "en/observability/opik", + "en/observability/patronus-evaluation", + "en/observability/portkey", + "en/observability/weave", + "en/observability/truefoundry" + ] + }, + { + "group": "Learn", + "pages": [ + "en/learn/overview", + "en/learn/llm-selection-guide", + "en/learn/conditional-tasks", + "en/learn/coding-agents", + "en/learn/create-custom-tools", + "en/learn/custom-llm", + "en/learn/custom-manager-agent", + "en/learn/customizing-agents", + "en/learn/dalle-image-generation", + "en/learn/force-tool-output-as-result", + "en/learn/hierarchical-process", + "en/learn/human-input-on-execution", + "en/learn/human-in-the-loop", + "en/learn/human-feedback-in-flows", + "en/learn/kickoff-async", + "en/learn/kickoff-for-each", + "en/learn/llm-connections", + "en/learn/litellm-removal-guide", + "en/learn/multimodal-agents", + "en/learn/replay-tasks-from-latest-crew-kickoff", + "en/learn/sequential-process", + "en/learn/using-annotations", + "en/learn/execution-hooks", + "en/learn/llm-hooks", + "en/learn/tool-hooks" + ] + }, + { + "group": "Telemetry", + "pages": [ + "en/telemetry" + ] + } + ] + }, + { + "tab": "AMP", + "icon": "briefcase", + "groups": [ + { + "group": "Getting Started", + "pages": [ + "en/enterprise/introduction" + ] + }, + { + "group": "Build", + "pages": [ + "en/enterprise/features/automations", + "en/enterprise/features/crew-studio", + "en/enterprise/features/marketplace", + "en/enterprise/features/agent-repositories", + "en/enterprise/features/tools-and-integrations", + "en/enterprise/features/pii-trace-redactions" + ] + }, + { + "group": "Operate", + "pages": [ + "en/enterprise/features/traces", + "en/enterprise/features/webhook-streaming", + "en/enterprise/features/hallucination-guardrail", + "en/enterprise/features/flow-hitl-management" + ] + }, + { + "group": "Manage", + "pages": [ + "en/enterprise/features/rbac" + ] + }, + { + "group": "Integration Docs", + "pages": [ + "en/enterprise/integrations/asana", + "en/enterprise/integrations/box", + "en/enterprise/integrations/clickup", + "en/enterprise/integrations/github", + "en/enterprise/integrations/gmail", + "en/enterprise/integrations/google_calendar", + "en/enterprise/integrations/google_contacts", + "en/enterprise/integrations/google_docs", + "en/enterprise/integrations/google_drive", + "en/enterprise/integrations/google_sheets", + "en/enterprise/integrations/google_slides", + "en/enterprise/integrations/hubspot", + "en/enterprise/integrations/jira", + "en/enterprise/integrations/linear", + "en/enterprise/integrations/microsoft_excel", + "en/enterprise/integrations/microsoft_onedrive", + "en/enterprise/integrations/microsoft_outlook", + "en/enterprise/integrations/microsoft_sharepoint", + "en/enterprise/integrations/microsoft_teams", + "en/enterprise/integrations/microsoft_word", + "en/enterprise/integrations/notion", + "en/enterprise/integrations/salesforce", + "en/enterprise/integrations/shopify", + "en/enterprise/integrations/slack", + "en/enterprise/integrations/stripe", + "en/enterprise/integrations/zendesk" + ] + }, + { + "group": "Triggers", + "pages": [ + "en/enterprise/guides/automation-triggers", + "en/enterprise/guides/gmail-trigger", + "en/enterprise/guides/google-calendar-trigger", + "en/enterprise/guides/google-drive-trigger", + "en/enterprise/guides/outlook-trigger", + "en/enterprise/guides/onedrive-trigger", + "en/enterprise/guides/microsoft-teams-trigger", + "en/enterprise/guides/slack-trigger", + "en/enterprise/guides/hubspot-trigger", + "en/enterprise/guides/salesforce-trigger", + "en/enterprise/guides/zapier-trigger" + ] + }, + { + "group": "How-To Guides", + "pages": [ + "en/enterprise/guides/build-crew", + "en/enterprise/guides/prepare-for-deployment", + "en/enterprise/guides/deploy-to-amp", + "en/enterprise/guides/private-package-registry", + "en/enterprise/guides/kickoff-crew", + "en/enterprise/guides/update-crew", + "en/enterprise/guides/enable-crew-studio", + "en/enterprise/guides/capture_telemetry_logs", + "en/enterprise/guides/azure-openai-setup", + "en/enterprise/guides/tool-repository", + "en/enterprise/guides/custom-mcp-server", + "en/enterprise/guides/react-component-export", + "en/enterprise/guides/team-management", + "en/enterprise/guides/human-in-the-loop", + "en/enterprise/guides/webhook-automation" + ] + }, + { + "group": "Resources", + "pages": [ + "en/enterprise/resources/frequently-asked-questions" + ] + } + ] + }, + { + "tab": "API Reference", + "icon": "magnifying-glass", + "groups": [ + { + "group": "Getting Started", + "pages": [ + "en/api-reference/introduction", + "en/api-reference/inputs", + "en/api-reference/kickoff", + "en/api-reference/resume", + "en/api-reference/status" + ] + } + ] + }, + { + "tab": "Examples", + "icon": "code", + "groups": [ + { + "group": "Examples", + "pages": [ + "en/examples/example", + "en/examples/cookbooks" + ] + } + ] + }, + { + "tab": "Changelog", + "icon": "clock", + "groups": [ + { + "group": "Release Notes", + "pages": [ + "en/changelog" + ] + } + ] + } + ] + }, { "version": "v1.11.0", "tabs": [ @@ -1960,7 +2429,7 @@ }, "versions": [ { - "version": "v1.11.1", + "version": "v1.12.0", "default": true, "tabs": [ { @@ -2414,6 +2883,460 @@ } ] }, + { + "version": "v1.11.1", + "tabs": [ + { + "tab": "Início", + "icon": "house", + "groups": [ + { + "group": "Bem-vindo", + "pages": [ + "pt-BR/index" + ] + } + ] + }, + { + "tab": "Documentação", + "icon": "book-open", + "groups": [ + { + "group": "Começando", + "pages": [ + "pt-BR/introduction", + "pt-BR/installation", + "pt-BR/quickstart" + ] + }, + { + "group": "Guias", + "pages": [ + { + "group": "Estratégia", + "icon": "compass", + "pages": [ + "pt-BR/guides/concepts/evaluating-use-cases" + ] + }, + { + "group": "Agentes", + "icon": "user", + "pages": [ + "pt-BR/guides/agents/crafting-effective-agents" + ] + }, + { + "group": "Crews", + "icon": "users", + "pages": [ + "pt-BR/guides/crews/first-crew" + ] + }, + { + "group": "Flows", + "icon": "code-branch", + "pages": [ + "pt-BR/guides/flows/first-flow", + "pt-BR/guides/flows/mastering-flow-state" + ] + }, + { + "group": "Ferramentas", + "icon": "wrench", + "pages": [ + "pt-BR/guides/tools/publish-custom-tools" + ] + }, + { + "group": "Ferramentas de Codificação", + "icon": "terminal", + "pages": [ + "pt-BR/guides/coding-tools/agents-md" + ] + }, + { + "group": "Avançado", + "icon": "gear", + "pages": [ + "pt-BR/guides/advanced/customizing-prompts", + "pt-BR/guides/advanced/fingerprinting" + ] + }, + { + "group": "Migração", + "icon": "shuffle", + "pages": [ + "pt-BR/guides/migration/migrating-from-langgraph" + ] + } + ] + }, + { + "group": "Conceitos-Chave", + "pages": [ + "pt-BR/concepts/agents", + "pt-BR/concepts/tasks", + "pt-BR/concepts/crews", + "pt-BR/concepts/flows", + "pt-BR/concepts/production-architecture", + "pt-BR/concepts/knowledge", + "pt-BR/concepts/skills", + "pt-BR/concepts/llms", + "pt-BR/concepts/files", + "pt-BR/concepts/processes", + "pt-BR/concepts/collaboration", + "pt-BR/concepts/training", + "pt-BR/concepts/memory", + "pt-BR/concepts/reasoning", + "pt-BR/concepts/planning", + "pt-BR/concepts/testing", + "pt-BR/concepts/cli", + "pt-BR/concepts/tools", + "pt-BR/concepts/event-listener" + ] + }, + { + "group": "Integração MCP", + "pages": [ + "pt-BR/mcp/overview", + "pt-BR/mcp/dsl-integration", + "pt-BR/mcp/stdio", + "pt-BR/mcp/sse", + "pt-BR/mcp/streamable-http", + "pt-BR/mcp/multiple-servers", + "pt-BR/mcp/security" + ] + }, + { + "group": "Ferramentas", + "pages": [ + "pt-BR/tools/overview", + { + "group": "Arquivo & Documento", + "icon": "folder-open", + "pages": [ + "pt-BR/tools/file-document/overview", + "pt-BR/tools/file-document/filereadtool", + "pt-BR/tools/file-document/filewritetool", + "pt-BR/tools/file-document/pdfsearchtool", + "pt-BR/tools/file-document/docxsearchtool", + "pt-BR/tools/file-document/mdxsearchtool", + "pt-BR/tools/file-document/xmlsearchtool", + "pt-BR/tools/file-document/txtsearchtool", + "pt-BR/tools/file-document/jsonsearchtool", + "pt-BR/tools/file-document/csvsearchtool", + "pt-BR/tools/file-document/directorysearchtool", + "pt-BR/tools/file-document/directoryreadtool" + ] + }, + { + "group": "Web Scraping & Navegação", + "icon": "globe", + "pages": [ + "pt-BR/tools/web-scraping/overview", + "pt-BR/tools/web-scraping/scrapewebsitetool", + "pt-BR/tools/web-scraping/scrapeelementfromwebsitetool", + "pt-BR/tools/web-scraping/scrapflyscrapetool", + "pt-BR/tools/web-scraping/seleniumscrapingtool", + "pt-BR/tools/web-scraping/scrapegraphscrapetool", + "pt-BR/tools/web-scraping/spidertool", + "pt-BR/tools/web-scraping/browserbaseloadtool", + "pt-BR/tools/web-scraping/hyperbrowserloadtool", + "pt-BR/tools/web-scraping/stagehandtool", + "pt-BR/tools/web-scraping/firecrawlcrawlwebsitetool", + "pt-BR/tools/web-scraping/firecrawlscrapewebsitetool", + "pt-BR/tools/web-scraping/oxylabsscraperstool" + ] + }, + { + "group": "Pesquisa", + "icon": "magnifying-glass", + "pages": [ + "pt-BR/tools/search-research/overview", + "pt-BR/tools/search-research/serperdevtool", + "pt-BR/tools/search-research/bravesearchtool", + "pt-BR/tools/search-research/exasearchtool", + "pt-BR/tools/search-research/linkupsearchtool", + "pt-BR/tools/search-research/githubsearchtool", + "pt-BR/tools/search-research/websitesearchtool", + "pt-BR/tools/search-research/codedocssearchtool", + "pt-BR/tools/search-research/youtubechannelsearchtool", + "pt-BR/tools/search-research/youtubevideosearchtool" + ] + }, + { + "group": "Dados", + "icon": "database", + "pages": [ + "pt-BR/tools/database-data/overview", + "pt-BR/tools/database-data/mysqltool", + "pt-BR/tools/database-data/pgsearchtool", + "pt-BR/tools/database-data/snowflakesearchtool", + "pt-BR/tools/database-data/nl2sqltool", + "pt-BR/tools/database-data/qdrantvectorsearchtool", + "pt-BR/tools/database-data/weaviatevectorsearchtool" + ] + }, + { + "group": "IA & Machine Learning", + "icon": "brain", + "pages": [ + "pt-BR/tools/ai-ml/overview", + "pt-BR/tools/ai-ml/dalletool", + "pt-BR/tools/ai-ml/visiontool", + "pt-BR/tools/ai-ml/aimindtool", + "pt-BR/tools/ai-ml/llamaindextool", + "pt-BR/tools/ai-ml/langchaintool", + "pt-BR/tools/ai-ml/ragtool", + "pt-BR/tools/ai-ml/codeinterpretertool" + ] + }, + { + "group": "Cloud & Armazenamento", + "icon": "cloud", + "pages": [ + "pt-BR/tools/cloud-storage/overview", + "pt-BR/tools/cloud-storage/s3readertool", + "pt-BR/tools/cloud-storage/s3writertool", + "pt-BR/tools/cloud-storage/bedrockkbretriever" + ] + }, + { + "group": "Integrations", + "icon": "plug", + "pages": [ + "pt-BR/tools/integration/overview", + "pt-BR/tools/integration/bedrockinvokeagenttool", + "pt-BR/tools/integration/crewaiautomationtool" + ] + }, + { + "group": "Automação", + "icon": "bolt", + "pages": [ + "pt-BR/tools/automation/overview", + "pt-BR/tools/automation/apifyactorstool", + "pt-BR/tools/automation/composiotool", + "pt-BR/tools/automation/multiontool" + ] + } + ] + }, + { + "group": "Observabilidade", + "pages": [ + "pt-BR/observability/tracing", + "pt-BR/observability/overview", + "pt-BR/observability/arize-phoenix", + "pt-BR/observability/braintrust", + "pt-BR/observability/datadog", + "pt-BR/observability/galileo", + "pt-BR/observability/langdb", + "pt-BR/observability/langfuse", + "pt-BR/observability/langtrace", + "pt-BR/observability/maxim", + "pt-BR/observability/mlflow", + "pt-BR/observability/openlit", + "pt-BR/observability/opik", + "pt-BR/observability/patronus-evaluation", + "pt-BR/observability/portkey", + "pt-BR/observability/weave", + "pt-BR/observability/truefoundry" + ] + }, + { + "group": "Aprenda", + "pages": [ + "pt-BR/learn/overview", + "pt-BR/learn/llm-selection-guide", + "pt-BR/learn/conditional-tasks", + "pt-BR/learn/coding-agents", + "pt-BR/learn/create-custom-tools", + "pt-BR/learn/custom-llm", + "pt-BR/learn/custom-manager-agent", + "pt-BR/learn/customizing-agents", + "pt-BR/learn/dalle-image-generation", + "pt-BR/learn/force-tool-output-as-result", + "pt-BR/learn/hierarchical-process", + "pt-BR/learn/human-input-on-execution", + "pt-BR/learn/human-in-the-loop", + "pt-BR/learn/human-feedback-in-flows", + "pt-BR/learn/kickoff-async", + "pt-BR/learn/kickoff-for-each", + "pt-BR/learn/llm-connections", + "pt-BR/learn/multimodal-agents", + "pt-BR/learn/replay-tasks-from-latest-crew-kickoff", + "pt-BR/learn/sequential-process", + "pt-BR/learn/using-annotations", + "pt-BR/learn/execution-hooks", + "pt-BR/learn/llm-hooks", + "pt-BR/learn/tool-hooks" + ] + }, + { + "group": "Telemetria", + "pages": [ + "pt-BR/telemetry" + ] + } + ] + }, + { + "tab": "AMP", + "icon": "briefcase", + "groups": [ + { + "group": "Começando", + "pages": [ + "pt-BR/enterprise/introduction" + ] + }, + { + "group": "Construir", + "pages": [ + "pt-BR/enterprise/features/automations", + "pt-BR/enterprise/features/crew-studio", + "pt-BR/enterprise/features/marketplace", + "pt-BR/enterprise/features/agent-repositories", + "pt-BR/enterprise/features/tools-and-integrations", + "pt-BR/enterprise/features/pii-trace-redactions" + ] + }, + { + "group": "Operar", + "pages": [ + "pt-BR/enterprise/features/traces", + "pt-BR/enterprise/features/webhook-streaming", + "pt-BR/enterprise/features/hallucination-guardrail", + "pt-BR/enterprise/features/flow-hitl-management" + ] + }, + { + "group": "Gerenciar", + "pages": [ + "pt-BR/enterprise/features/rbac" + ] + }, + { + "group": "Documentação de Integração", + "pages": [ + "pt-BR/enterprise/integrations/asana", + "pt-BR/enterprise/integrations/box", + "pt-BR/enterprise/integrations/clickup", + "pt-BR/enterprise/integrations/github", + "pt-BR/enterprise/integrations/gmail", + "pt-BR/enterprise/integrations/google_calendar", + "pt-BR/enterprise/integrations/google_contacts", + "pt-BR/enterprise/integrations/google_docs", + "pt-BR/enterprise/integrations/google_drive", + "pt-BR/enterprise/integrations/google_sheets", + "pt-BR/enterprise/integrations/google_slides", + "pt-BR/enterprise/integrations/hubspot", + "pt-BR/enterprise/integrations/jira", + "pt-BR/enterprise/integrations/linear", + "pt-BR/enterprise/integrations/microsoft_excel", + "pt-BR/enterprise/integrations/microsoft_onedrive", + "pt-BR/enterprise/integrations/microsoft_outlook", + "pt-BR/enterprise/integrations/microsoft_sharepoint", + "pt-BR/enterprise/integrations/microsoft_teams", + "pt-BR/enterprise/integrations/microsoft_word", + "pt-BR/enterprise/integrations/notion", + "pt-BR/enterprise/integrations/salesforce", + "pt-BR/enterprise/integrations/shopify", + "pt-BR/enterprise/integrations/slack", + "pt-BR/enterprise/integrations/stripe", + "pt-BR/enterprise/integrations/zendesk" + ] + }, + { + "group": "Guias", + "pages": [ + "pt-BR/enterprise/guides/build-crew", + "pt-BR/enterprise/guides/prepare-for-deployment", + "pt-BR/enterprise/guides/deploy-to-amp", + "pt-BR/enterprise/guides/private-package-registry", + "pt-BR/enterprise/guides/kickoff-crew", + "pt-BR/enterprise/guides/update-crew", + "pt-BR/enterprise/guides/enable-crew-studio", + "pt-BR/enterprise/guides/capture_telemetry_logs", + "pt-BR/enterprise/guides/azure-openai-setup", + "pt-BR/enterprise/guides/tool-repository", + "pt-BR/enterprise/guides/custom-mcp-server", + "pt-BR/enterprise/guides/react-component-export", + "pt-BR/enterprise/guides/team-management", + "pt-BR/enterprise/guides/human-in-the-loop", + "pt-BR/enterprise/guides/webhook-automation" + ] + }, + { + "group": "Triggers", + "pages": [ + "pt-BR/enterprise/guides/automation-triggers", + "pt-BR/enterprise/guides/gmail-trigger", + "pt-BR/enterprise/guides/google-calendar-trigger", + "pt-BR/enterprise/guides/google-drive-trigger", + "pt-BR/enterprise/guides/outlook-trigger", + "pt-BR/enterprise/guides/onedrive-trigger", + "pt-BR/enterprise/guides/microsoft-teams-trigger", + "pt-BR/enterprise/guides/slack-trigger", + "pt-BR/enterprise/guides/hubspot-trigger", + "pt-BR/enterprise/guides/salesforce-trigger", + "pt-BR/enterprise/guides/zapier-trigger" + ] + }, + { + "group": "Recursos", + "pages": [ + "pt-BR/enterprise/resources/frequently-asked-questions" + ] + } + ] + }, + { + "tab": "Referência da API", + "icon": "magnifying-glass", + "groups": [ + { + "group": "Começando", + "pages": [ + "pt-BR/api-reference/introduction", + "pt-BR/api-reference/inputs", + "pt-BR/api-reference/kickoff", + "pt-BR/api-reference/resume", + "pt-BR/api-reference/status" + ] + } + ] + }, + { + "tab": "Exemplos", + "icon": "code", + "groups": [ + { + "group": "Exemplos", + "pages": [ + "pt-BR/examples/example", + "pt-BR/examples/cookbooks" + ] + } + ] + }, + { + "tab": "Notas de Versão", + "icon": "clock", + "groups": [ + { + "group": "Notas de Versão", + "pages": [ + "pt-BR/changelog" + ] + } + ] + } + ] + }, { "version": "v1.11.0", "tabs": [ @@ -3804,7 +4727,7 @@ }, "versions": [ { - "version": "v1.11.1", + "version": "v1.12.0", "default": true, "tabs": [ { @@ -4270,6 +5193,472 @@ } ] }, + { + "version": "v1.11.1", + "tabs": [ + { + "tab": "홈", + "icon": "house", + "groups": [ + { + "group": "환영합니다", + "pages": [ + "ko/index" + ] + } + ] + }, + { + "tab": "기술 문서", + "icon": "book-open", + "groups": [ + { + "group": "시작 안내", + "pages": [ + "ko/introduction", + "ko/installation", + "ko/quickstart" + ] + }, + { + "group": "가이드", + "pages": [ + { + "group": "전략", + "icon": "compass", + "pages": [ + "ko/guides/concepts/evaluating-use-cases" + ] + }, + { + "group": "에이전트 (Agents)", + "icon": "user", + "pages": [ + "ko/guides/agents/crafting-effective-agents" + ] + }, + { + "group": "크루 (Crews)", + "icon": "users", + "pages": [ + "ko/guides/crews/first-crew" + ] + }, + { + "group": "플로우 (Flows)", + "icon": "code-branch", + "pages": [ + "ko/guides/flows/first-flow", + "ko/guides/flows/mastering-flow-state" + ] + }, + { + "group": "도구", + "icon": "wrench", + "pages": [ + "ko/guides/tools/publish-custom-tools" + ] + }, + { + "group": "코딩 도구", + "icon": "terminal", + "pages": [ + "ko/guides/coding-tools/agents-md" + ] + }, + { + "group": "고급", + "icon": "gear", + "pages": [ + "ko/guides/advanced/customizing-prompts", + "ko/guides/advanced/fingerprinting" + ] + }, + { + "group": "마이그레이션", + "icon": "shuffle", + "pages": [ + "ko/guides/migration/migrating-from-langgraph" + ] + } + ] + }, + { + "group": "핵심 개념", + "pages": [ + "ko/concepts/agents", + "ko/concepts/tasks", + "ko/concepts/crews", + "ko/concepts/flows", + "ko/concepts/production-architecture", + "ko/concepts/knowledge", + "ko/concepts/skills", + "ko/concepts/llms", + "ko/concepts/files", + "ko/concepts/processes", + "ko/concepts/collaboration", + "ko/concepts/training", + "ko/concepts/memory", + "ko/concepts/reasoning", + "ko/concepts/planning", + "ko/concepts/testing", + "ko/concepts/cli", + "ko/concepts/tools", + "ko/concepts/event-listener" + ] + }, + { + "group": "MCP 통합", + "pages": [ + "ko/mcp/overview", + "ko/mcp/dsl-integration", + "ko/mcp/stdio", + "ko/mcp/sse", + "ko/mcp/streamable-http", + "ko/mcp/multiple-servers", + "ko/mcp/security" + ] + }, + { + "group": "도구 (Tools)", + "pages": [ + "ko/tools/overview", + { + "group": "파일 & 문서", + "icon": "folder-open", + "pages": [ + "ko/tools/file-document/overview", + "ko/tools/file-document/filereadtool", + "ko/tools/file-document/filewritetool", + "ko/tools/file-document/pdfsearchtool", + "ko/tools/file-document/docxsearchtool", + "ko/tools/file-document/mdxsearchtool", + "ko/tools/file-document/xmlsearchtool", + "ko/tools/file-document/txtsearchtool", + "ko/tools/file-document/jsonsearchtool", + "ko/tools/file-document/csvsearchtool", + "ko/tools/file-document/directorysearchtool", + "ko/tools/file-document/directoryreadtool", + "ko/tools/file-document/ocrtool", + "ko/tools/file-document/pdf-text-writing-tool" + ] + }, + { + "group": "웹 스크래핑 & 브라우징", + "icon": "globe", + "pages": [ + "ko/tools/web-scraping/overview", + "ko/tools/web-scraping/scrapewebsitetool", + "ko/tools/web-scraping/scrapeelementfromwebsitetool", + "ko/tools/web-scraping/scrapflyscrapetool", + "ko/tools/web-scraping/seleniumscrapingtool", + "ko/tools/web-scraping/scrapegraphscrapetool", + "ko/tools/web-scraping/spidertool", + "ko/tools/web-scraping/browserbaseloadtool", + "ko/tools/web-scraping/hyperbrowserloadtool", + "ko/tools/web-scraping/stagehandtool", + "ko/tools/web-scraping/firecrawlcrawlwebsitetool", + "ko/tools/web-scraping/firecrawlscrapewebsitetool", + "ko/tools/web-scraping/oxylabsscraperstool", + "ko/tools/web-scraping/brightdata-tools" + ] + }, + { + "group": "검색 및 연구", + "icon": "magnifying-glass", + "pages": [ + "ko/tools/search-research/overview", + "ko/tools/search-research/serperdevtool", + "ko/tools/search-research/bravesearchtool", + "ko/tools/search-research/exasearchtool", + "ko/tools/search-research/linkupsearchtool", + "ko/tools/search-research/githubsearchtool", + "ko/tools/search-research/websitesearchtool", + "ko/tools/search-research/codedocssearchtool", + "ko/tools/search-research/youtubechannelsearchtool", + "ko/tools/search-research/youtubevideosearchtool", + "ko/tools/search-research/tavilysearchtool", + "ko/tools/search-research/tavilyextractortool", + "ko/tools/search-research/arxivpapertool", + "ko/tools/search-research/serpapi-googlesearchtool", + "ko/tools/search-research/serpapi-googleshoppingtool", + "ko/tools/search-research/databricks-query-tool" + ] + }, + { + "group": "데이터베이스 & 데이터", + "icon": "database", + "pages": [ + "ko/tools/database-data/overview", + "ko/tools/database-data/mysqltool", + "ko/tools/database-data/pgsearchtool", + "ko/tools/database-data/snowflakesearchtool", + "ko/tools/database-data/nl2sqltool", + "ko/tools/database-data/qdrantvectorsearchtool", + "ko/tools/database-data/weaviatevectorsearchtool", + "ko/tools/database-data/mongodbvectorsearchtool", + "ko/tools/database-data/singlestoresearchtool" + ] + }, + { + "group": "인공지능 & 머신러닝", + "icon": "brain", + "pages": [ + "ko/tools/ai-ml/overview", + "ko/tools/ai-ml/dalletool", + "ko/tools/ai-ml/visiontool", + "ko/tools/ai-ml/aimindtool", + "ko/tools/ai-ml/llamaindextool", + "ko/tools/ai-ml/langchaintool", + "ko/tools/ai-ml/ragtool", + "ko/tools/ai-ml/codeinterpretertool" + ] + }, + { + "group": "클라우드 & 스토리지", + "icon": "cloud", + "pages": [ + "ko/tools/cloud-storage/overview", + "ko/tools/cloud-storage/s3readertool", + "ko/tools/cloud-storage/s3writertool", + "ko/tools/cloud-storage/bedrockkbretriever" + ] + }, + { + "group": "Integrations", + "icon": "plug", + "pages": [ + "ko/tools/integration/overview", + "ko/tools/integration/bedrockinvokeagenttool", + "ko/tools/integration/crewaiautomationtool" + ] + }, + { + "group": "자동화", + "icon": "bolt", + "pages": [ + "ko/tools/automation/overview", + "ko/tools/automation/apifyactorstool", + "ko/tools/automation/composiotool", + "ko/tools/automation/multiontool", + "ko/tools/automation/zapieractionstool" + ] + } + ] + }, + { + "group": "Observability", + "pages": [ + "ko/observability/tracing", + "ko/observability/overview", + "ko/observability/arize-phoenix", + "ko/observability/braintrust", + "ko/observability/datadog", + "ko/observability/galileo", + "ko/observability/langdb", + "ko/observability/langfuse", + "ko/observability/langtrace", + "ko/observability/maxim", + "ko/observability/mlflow", + "ko/observability/neatlogs", + "ko/observability/openlit", + "ko/observability/opik", + "ko/observability/patronus-evaluation", + "ko/observability/portkey", + "ko/observability/weave" + ] + }, + { + "group": "학습", + "pages": [ + "ko/learn/overview", + "ko/learn/llm-selection-guide", + "ko/learn/conditional-tasks", + "ko/learn/coding-agents", + "ko/learn/create-custom-tools", + "ko/learn/custom-llm", + "ko/learn/custom-manager-agent", + "ko/learn/customizing-agents", + "ko/learn/dalle-image-generation", + "ko/learn/force-tool-output-as-result", + "ko/learn/hierarchical-process", + "ko/learn/human-input-on-execution", + "ko/learn/human-in-the-loop", + "ko/learn/human-feedback-in-flows", + "ko/learn/kickoff-async", + "ko/learn/kickoff-for-each", + "ko/learn/llm-connections", + "ko/learn/multimodal-agents", + "ko/learn/replay-tasks-from-latest-crew-kickoff", + "ko/learn/sequential-process", + "ko/learn/using-annotations", + "ko/learn/execution-hooks", + "ko/learn/llm-hooks", + "ko/learn/tool-hooks" + ] + }, + { + "group": "Telemetry", + "pages": [ + "ko/telemetry" + ] + } + ] + }, + { + "tab": "엔터프라이즈", + "icon": "briefcase", + "groups": [ + { + "group": "시작 안내", + "pages": [ + "ko/enterprise/introduction" + ] + }, + { + "group": "빌드", + "pages": [ + "ko/enterprise/features/automations", + "ko/enterprise/features/crew-studio", + "ko/enterprise/features/marketplace", + "ko/enterprise/features/agent-repositories", + "ko/enterprise/features/tools-and-integrations", + "ko/enterprise/features/pii-trace-redactions" + ] + }, + { + "group": "운영", + "pages": [ + "ko/enterprise/features/traces", + "ko/enterprise/features/webhook-streaming", + "ko/enterprise/features/hallucination-guardrail", + "ko/enterprise/features/flow-hitl-management" + ] + }, + { + "group": "관리", + "pages": [ + "ko/enterprise/features/rbac" + ] + }, + { + "group": "통합 문서", + "pages": [ + "ko/enterprise/integrations/asana", + "ko/enterprise/integrations/box", + "ko/enterprise/integrations/clickup", + "ko/enterprise/integrations/github", + "ko/enterprise/integrations/gmail", + "ko/enterprise/integrations/google_calendar", + "ko/enterprise/integrations/google_contacts", + "ko/enterprise/integrations/google_docs", + "ko/enterprise/integrations/google_drive", + "ko/enterprise/integrations/google_sheets", + "ko/enterprise/integrations/google_slides", + "ko/enterprise/integrations/hubspot", + "ko/enterprise/integrations/jira", + "ko/enterprise/integrations/linear", + "ko/enterprise/integrations/microsoft_excel", + "ko/enterprise/integrations/microsoft_onedrive", + "ko/enterprise/integrations/microsoft_outlook", + "ko/enterprise/integrations/microsoft_sharepoint", + "ko/enterprise/integrations/microsoft_teams", + "ko/enterprise/integrations/microsoft_word", + "ko/enterprise/integrations/notion", + "ko/enterprise/integrations/salesforce", + "ko/enterprise/integrations/shopify", + "ko/enterprise/integrations/slack", + "ko/enterprise/integrations/stripe", + "ko/enterprise/integrations/zendesk" + ] + }, + { + "group": "How-To Guides", + "pages": [ + "ko/enterprise/guides/build-crew", + "ko/enterprise/guides/prepare-for-deployment", + "ko/enterprise/guides/deploy-to-amp", + "ko/enterprise/guides/private-package-registry", + "ko/enterprise/guides/kickoff-crew", + "ko/enterprise/guides/update-crew", + "ko/enterprise/guides/enable-crew-studio", + "ko/enterprise/guides/capture_telemetry_logs", + "ko/enterprise/guides/azure-openai-setup", + "ko/enterprise/guides/tool-repository", + "ko/enterprise/guides/custom-mcp-server", + "ko/enterprise/guides/react-component-export", + "ko/enterprise/guides/team-management", + "ko/enterprise/guides/human-in-the-loop", + "ko/enterprise/guides/webhook-automation" + ] + }, + { + "group": "트리거", + "pages": [ + "ko/enterprise/guides/automation-triggers", + "ko/enterprise/guides/gmail-trigger", + "ko/enterprise/guides/google-calendar-trigger", + "ko/enterprise/guides/google-drive-trigger", + "ko/enterprise/guides/outlook-trigger", + "ko/enterprise/guides/onedrive-trigger", + "ko/enterprise/guides/microsoft-teams-trigger", + "ko/enterprise/guides/slack-trigger", + "ko/enterprise/guides/hubspot-trigger", + "ko/enterprise/guides/salesforce-trigger", + "ko/enterprise/guides/zapier-trigger" + ] + }, + { + "group": "학습 자원", + "pages": [ + "ko/enterprise/resources/frequently-asked-questions" + ] + } + ] + }, + { + "tab": "API 레퍼런스", + "icon": "magnifying-glass", + "groups": [ + { + "group": "시작 안내", + "pages": [ + "ko/api-reference/introduction", + "ko/api-reference/inputs", + "ko/api-reference/kickoff", + "ko/api-reference/resume", + "ko/api-reference/status" + ] + } + ] + }, + { + "tab": "예시", + "icon": "code", + "groups": [ + { + "group": "예시", + "pages": [ + "ko/examples/example", + "ko/examples/cookbooks" + ] + } + ] + }, + { + "tab": "변경 로그", + "icon": "clock", + "groups": [ + { + "group": "릴리스 노트", + "pages": [ + "ko/changelog" + ] + } + ] + } + ] + }, { "version": "v1.11.0", "tabs": [ @@ -5696,7 +7085,7 @@ }, "versions": [ { - "version": "v1.11.1", + "version": "v1.12.0", "default": true, "tabs": [ { @@ -6162,6 +7551,472 @@ } ] }, + { + "version": "v1.11.1", + "tabs": [ + { + "tab": "الرئيسية", + "icon": "house", + "groups": [ + { + "group": "مرحباً", + "pages": [ + "ar/index" + ] + } + ] + }, + { + "tab": "التقنية التوثيق", + "icon": "book-open", + "groups": [ + { + "group": "البدء", + "pages": [ + "ar/introduction", + "ar/installation", + "ar/quickstart" + ] + }, + { + "group": "الأدلّة", + "pages": [ + { + "group": "الاستراتيجية", + "icon": "compass", + "pages": [ + "ar/guides/concepts/evaluating-use-cases" + ] + }, + { + "group": "الوكلاء", + "icon": "user", + "pages": [ + "ar/guides/agents/crafting-effective-agents" + ] + }, + { + "group": "الطواقم", + "icon": "users", + "pages": [ + "ar/guides/crews/first-crew" + ] + }, + { + "group": "التدفقات", + "icon": "code-branch", + "pages": [ + "ar/guides/flows/first-flow", + "ar/guides/flows/mastering-flow-state" + ] + }, + { + "group": "الأدوات", + "icon": "wrench", + "pages": [ + "ar/guides/tools/publish-custom-tools" + ] + }, + { + "group": "أدوات البرمجة", + "icon": "terminal", + "pages": [ + "ar/guides/coding-tools/agents-md" + ] + }, + { + "group": "متقدّم", + "icon": "gear", + "pages": [ + "ar/guides/advanced/customizing-prompts", + "ar/guides/advanced/fingerprinting" + ] + }, + { + "group": "الترحيل", + "icon": "shuffle", + "pages": [ + "ar/guides/migration/migrating-from-langgraph" + ] + } + ] + }, + { + "group": "المفاهيم الأساسية", + "pages": [ + "ar/concepts/agents", + "ar/concepts/tasks", + "ar/concepts/crews", + "ar/concepts/flows", + "ar/concepts/production-architecture", + "ar/concepts/knowledge", + "ar/concepts/skills", + "ar/concepts/llms", + "ar/concepts/files", + "ar/concepts/processes", + "ar/concepts/collaboration", + "ar/concepts/training", + "ar/concepts/memory", + "ar/concepts/reasoning", + "ar/concepts/planning", + "ar/concepts/testing", + "ar/concepts/cli", + "ar/concepts/tools", + "ar/concepts/event-listener" + ] + }, + { + "group": "تكامل MCP", + "pages": [ + "ar/mcp/overview", + "ar/mcp/dsl-integration", + "ar/mcp/stdio", + "ar/mcp/sse", + "ar/mcp/streamable-http", + "ar/mcp/multiple-servers", + "ar/mcp/security" + ] + }, + { + "group": "الأدوات", + "pages": [ + "ar/tools/overview", + { + "group": "الملفات والمستندات", + "icon": "folder-open", + "pages": [ + "ar/tools/file-document/overview", + "ar/tools/file-document/filereadtool", + "ar/tools/file-document/filewritetool", + "ar/tools/file-document/pdfsearchtool", + "ar/tools/file-document/docxsearchtool", + "ar/tools/file-document/mdxsearchtool", + "ar/tools/file-document/xmlsearchtool", + "ar/tools/file-document/txtsearchtool", + "ar/tools/file-document/jsonsearchtool", + "ar/tools/file-document/csvsearchtool", + "ar/tools/file-document/directorysearchtool", + "ar/tools/file-document/directoryreadtool", + "ar/tools/file-document/ocrtool", + "ar/tools/file-document/pdf-text-writing-tool" + ] + }, + { + "group": "استخراج بيانات الويب", + "icon": "globe", + "pages": [ + "ar/tools/web-scraping/overview", + "ar/tools/web-scraping/scrapewebsitetool", + "ar/tools/web-scraping/scrapeelementfromwebsitetool", + "ar/tools/web-scraping/scrapflyscrapetool", + "ar/tools/web-scraping/seleniumscrapingtool", + "ar/tools/web-scraping/scrapegraphscrapetool", + "ar/tools/web-scraping/spidertool", + "ar/tools/web-scraping/browserbaseloadtool", + "ar/tools/web-scraping/hyperbrowserloadtool", + "ar/tools/web-scraping/stagehandtool", + "ar/tools/web-scraping/firecrawlcrawlwebsitetool", + "ar/tools/web-scraping/firecrawlscrapewebsitetool", + "ar/tools/web-scraping/oxylabsscraperstool", + "ar/tools/web-scraping/brightdata-tools" + ] + }, + { + "group": "البحث والاستكشاف", + "icon": "magnifying-glass", + "pages": [ + "ar/tools/search-research/overview", + "ar/tools/search-research/serperdevtool", + "ar/tools/search-research/bravesearchtool", + "ar/tools/search-research/exasearchtool", + "ar/tools/search-research/linkupsearchtool", + "ar/tools/search-research/githubsearchtool", + "ar/tools/search-research/websitesearchtool", + "ar/tools/search-research/codedocssearchtool", + "ar/tools/search-research/youtubechannelsearchtool", + "ar/tools/search-research/youtubevideosearchtool", + "ar/tools/search-research/tavilysearchtool", + "ar/tools/search-research/tavilyextractortool", + "ar/tools/search-research/arxivpapertool", + "ar/tools/search-research/serpapi-googlesearchtool", + "ar/tools/search-research/serpapi-googleshoppingtool", + "ar/tools/search-research/databricks-query-tool" + ] + }, + { + "group": "قواعد البيانات", + "icon": "database", + "pages": [ + "ar/tools/database-data/overview", + "ar/tools/database-data/mysqltool", + "ar/tools/database-data/pgsearchtool", + "ar/tools/database-data/snowflakesearchtool", + "ar/tools/database-data/nl2sqltool", + "ar/tools/database-data/qdrantvectorsearchtool", + "ar/tools/database-data/weaviatevectorsearchtool", + "ar/tools/database-data/mongodbvectorsearchtool", + "ar/tools/database-data/singlestoresearchtool" + ] + }, + { + "group": "الذكاء الاصطناعي والتعلّم الآلي", + "icon": "brain", + "pages": [ + "ar/tools/ai-ml/overview", + "ar/tools/ai-ml/dalletool", + "ar/tools/ai-ml/visiontool", + "ar/tools/ai-ml/aimindtool", + "ar/tools/ai-ml/llamaindextool", + "ar/tools/ai-ml/langchaintool", + "ar/tools/ai-ml/ragtool", + "ar/tools/ai-ml/codeinterpretertool" + ] + }, + { + "group": "التخزين السحابي", + "icon": "cloud", + "pages": [ + "ar/tools/cloud-storage/overview", + "ar/tools/cloud-storage/s3readertool", + "ar/tools/cloud-storage/s3writertool", + "ar/tools/cloud-storage/bedrockkbretriever" + ] + }, + { + "group": "Integrations", + "icon": "plug", + "pages": [ + "ar/tools/integration/overview", + "ar/tools/integration/bedrockinvokeagenttool", + "ar/tools/integration/crewaiautomationtool" + ] + }, + { + "group": "الأتمتة", + "icon": "bolt", + "pages": [ + "ar/tools/automation/overview", + "ar/tools/automation/apifyactorstool", + "ar/tools/automation/composiotool", + "ar/tools/automation/multiontool", + "ar/tools/automation/zapieractionstool" + ] + } + ] + }, + { + "group": "Observability", + "pages": [ + "ar/observability/tracing", + "ar/observability/overview", + "ar/observability/arize-phoenix", + "ar/observability/braintrust", + "ar/observability/datadog", + "ar/observability/galileo", + "ar/observability/langdb", + "ar/observability/langfuse", + "ar/observability/langtrace", + "ar/observability/maxim", + "ar/observability/mlflow", + "ar/observability/neatlogs", + "ar/observability/openlit", + "ar/observability/opik", + "ar/observability/patronus-evaluation", + "ar/observability/portkey", + "ar/observability/weave" + ] + }, + { + "group": "التعلّم", + "pages": [ + "ar/learn/overview", + "ar/learn/llm-selection-guide", + "ar/learn/conditional-tasks", + "ar/learn/coding-agents", + "ar/learn/create-custom-tools", + "ar/learn/custom-llm", + "ar/learn/custom-manager-agent", + "ar/learn/customizing-agents", + "ar/learn/dalle-image-generation", + "ar/learn/force-tool-output-as-result", + "ar/learn/hierarchical-process", + "ar/learn/human-input-on-execution", + "ar/learn/human-in-the-loop", + "ar/learn/human-feedback-in-flows", + "ar/learn/kickoff-async", + "ar/learn/kickoff-for-each", + "ar/learn/llm-connections", + "ar/learn/multimodal-agents", + "ar/learn/replay-tasks-from-latest-crew-kickoff", + "ar/learn/sequential-process", + "ar/learn/using-annotations", + "ar/learn/execution-hooks", + "ar/learn/llm-hooks", + "ar/learn/tool-hooks" + ] + }, + { + "group": "Telemetry", + "pages": [ + "ar/telemetry" + ] + } + ] + }, + { + "tab": "المؤسسات", + "icon": "briefcase", + "groups": [ + { + "group": "البدء", + "pages": [ + "ar/enterprise/introduction" + ] + }, + { + "group": "البناء", + "pages": [ + "ar/enterprise/features/automations", + "ar/enterprise/features/crew-studio", + "ar/enterprise/features/marketplace", + "ar/enterprise/features/agent-repositories", + "ar/enterprise/features/tools-and-integrations", + "ar/enterprise/features/pii-trace-redactions" + ] + }, + { + "group": "العمليات", + "pages": [ + "ar/enterprise/features/traces", + "ar/enterprise/features/webhook-streaming", + "ar/enterprise/features/hallucination-guardrail", + "ar/enterprise/features/flow-hitl-management" + ] + }, + { + "group": "الإدارة", + "pages": [ + "ar/enterprise/features/rbac" + ] + }, + { + "group": "التكاملات", + "pages": [ + "ar/enterprise/integrations/asana", + "ar/enterprise/integrations/box", + "ar/enterprise/integrations/clickup", + "ar/enterprise/integrations/github", + "ar/enterprise/integrations/gmail", + "ar/enterprise/integrations/google_calendar", + "ar/enterprise/integrations/google_contacts", + "ar/enterprise/integrations/google_docs", + "ar/enterprise/integrations/google_drive", + "ar/enterprise/integrations/google_sheets", + "ar/enterprise/integrations/google_slides", + "ar/enterprise/integrations/hubspot", + "ar/enterprise/integrations/jira", + "ar/enterprise/integrations/linear", + "ar/enterprise/integrations/microsoft_excel", + "ar/enterprise/integrations/microsoft_onedrive", + "ar/enterprise/integrations/microsoft_outlook", + "ar/enterprise/integrations/microsoft_sharepoint", + "ar/enterprise/integrations/microsoft_teams", + "ar/enterprise/integrations/microsoft_word", + "ar/enterprise/integrations/notion", + "ar/enterprise/integrations/salesforce", + "ar/enterprise/integrations/shopify", + "ar/enterprise/integrations/slack", + "ar/enterprise/integrations/stripe", + "ar/enterprise/integrations/zendesk" + ] + }, + { + "group": "How-To Guides", + "pages": [ + "ar/enterprise/guides/build-crew", + "ar/enterprise/guides/prepare-for-deployment", + "ar/enterprise/guides/deploy-to-amp", + "ar/enterprise/guides/private-package-registry", + "ar/enterprise/guides/kickoff-crew", + "ar/enterprise/guides/update-crew", + "ar/enterprise/guides/enable-crew-studio", + "ar/enterprise/guides/capture_telemetry_logs", + "ar/enterprise/guides/azure-openai-setup", + "ar/enterprise/guides/tool-repository", + "ar/enterprise/guides/custom-mcp-server", + "ar/enterprise/guides/react-component-export", + "ar/enterprise/guides/team-management", + "ar/enterprise/guides/human-in-the-loop", + "ar/enterprise/guides/webhook-automation" + ] + }, + { + "group": "المشغّلات", + "pages": [ + "ar/enterprise/guides/automation-triggers", + "ar/enterprise/guides/gmail-trigger", + "ar/enterprise/guides/google-calendar-trigger", + "ar/enterprise/guides/google-drive-trigger", + "ar/enterprise/guides/outlook-trigger", + "ar/enterprise/guides/onedrive-trigger", + "ar/enterprise/guides/microsoft-teams-trigger", + "ar/enterprise/guides/slack-trigger", + "ar/enterprise/guides/hubspot-trigger", + "ar/enterprise/guides/salesforce-trigger", + "ar/enterprise/guides/zapier-trigger" + ] + }, + { + "group": "موارد التعلّم", + "pages": [ + "ar/enterprise/resources/frequently-asked-questions" + ] + } + ] + }, + { + "tab": "API المرجع", + "icon": "magnifying-glass", + "groups": [ + { + "group": "البدء", + "pages": [ + "ar/api-reference/introduction", + "ar/api-reference/inputs", + "ar/api-reference/kickoff", + "ar/api-reference/resume", + "ar/api-reference/status" + ] + } + ] + }, + { + "tab": "أمثلة", + "icon": "code", + "groups": [ + { + "group": "أمثلة", + "pages": [ + "ar/examples/example", + "ar/examples/cookbooks" + ] + } + ] + }, + { + "tab": "التغييرات السجلات", + "icon": "clock", + "groups": [ + { + "group": "سجل التغييرات", + "pages": [ + "ar/changelog" + ] + } + ] + } + ] + }, { "version": "v1.11.0", "tabs": [ diff --git a/docs/en/changelog.mdx b/docs/en/changelog.mdx index 23b863e94..77a776de2 100644 --- a/docs/en/changelog.mdx +++ b/docs/en/changelog.mdx @@ -4,6 +4,51 @@ description: "Product updates, improvements, and bug fixes for CrewAI" icon: "clock" mode: "wide" --- + + ## v1.12.0 + + [View release on GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.12.0) + + ## What's Changed + + ### Features + - Add Qdrant Edge storage backend for memory system + - Add docs-check command to analyze changes and generate docs with translations + - Add Arabic language support to changelog and release tooling + - Add modern standard Arabic translation of all documentation + - Add logout command in CLI + - Implement agent skills + - Implement automatic root_scope for hierarchical memory isolation + - Implement native OpenAI-compatible providers (OpenRouter, DeepSeek, Ollama, vLLM, Cerebras, Dashscope) + + ### Bug Fixes + - Fix bad credentials for traces batch push (404) + - Resolve multiple bugs in HITL flow system + - Resolve mypy errors in crewai-files and add all packages to CI type checks + - Resolve all strict mypy errors across crewai-tools package + - Resolve all mypy errors across crewai package + - Fix memory saving in agent + - Fix usage of __router_paths__ for listener+router methods in FlowMeta + - Raise value error on no file support + - Correct litellm quarantine wording in docs + - Use None check instead of isinstance for memory in human feedback learn + - Pin litellm upper bound to last tested version (1.82.6) + + ### Documentation + - Update changelog and version for v1.12.0 + - Add CONTRIBUTING.md + - Add guide for using CrewAI without LiteLLM + + ### Refactoring + - Refactor to deduplicate sync/async task execution and kickoff in agent + - Simplify internal plumbing from litellm (token counting, callbacks, feature detection, errors) + + ## Contributors + + @akaKuruma, @alex-clawd, @greysonlalonde, @iris-clawd, @joaomdmoura, @lorenzejay, @nicoferdi96 + + + ## v1.12.0a3 diff --git a/docs/ko/changelog.mdx b/docs/ko/changelog.mdx index 12efce93e..9fbb41352 100644 --- a/docs/ko/changelog.mdx +++ b/docs/ko/changelog.mdx @@ -4,6 +4,51 @@ description: "CrewAI의 제품 업데이트, 개선 사항 및 버그 수정" icon: "clock" mode: "wide" --- + + ## v1.12.0 + + [GitHub 릴리스 보기](https://github.com/crewAIInc/crewAI/releases/tag/1.12.0) + + ## 변경 사항 + + ### 기능 + - 메모리 시스템을 위한 Qdrant Edge 스토리지 백엔드 추가 + - 변경 사항을 분석하고 번역된 문서와 함께 문서를 생성하는 docs-check 명령어 추가 + - 변경 로그 및 릴리스 도구에 아랍어 지원 추가 + - 모든 문서의 현대 표준 아랍어 번역 추가 + - CLI에 로그아웃 명령어 추가 + - 에이전트 기술 구현 + - 계층적 메모리 격리를 위한 자동 root_scope 구현 + - OpenAI 호환 네이티브 제공자 구현 (OpenRouter, DeepSeek, Ollama, vLLM, Cerebras, Dashscope) + + ### 버그 수정 + - 트레이스 배치 푸시에 대한 잘못된 자격 증명 수정 (404) + - HITL 흐름 시스템의 여러 버그 해결 + - crewai-files의 mypy 오류 해결 및 모든 패키지를 CI 타입 검사에 추가 + - crewai-tools 패키지 전반의 모든 엄격한 mypy 오류 해결 + - crewai 패키지 전반의 모든 mypy 오류 해결 + - 에이전트의 메모리 절약 수정 + - FlowMeta에서 listener+router 메서드의 __router_paths__ 사용 수정 + - 파일 지원이 없을 때 값 오류 발생 + - 문서에서 litellm 격리 단어 수정 + - 인간 피드백 학습에서 메모리에 대한 isinstance 대신 None 체크 사용 + - litellm의 상한을 마지막 테스트된 버전(1.82.6)으로 고정 + + ### 문서 + - v1.12.0에 대한 변경 로그 및 버전 업데이트 + - CONTRIBUTING.md 추가 + - LiteLLM 없이 CrewAI를 사용하는 가이드 추가 + + ### 리팩토링 + - 에이전트에서 동기/비동기 작업 실행 및 시작을 중복 제거하도록 리팩토링 + - litellm의 내부 플러밍 단순화 (토큰 카운팅, 콜백, 기능 감지, 오류) + + ## 기여자 + + @akaKuruma, @alex-clawd, @greysonlalonde, @iris-clawd, @joaomdmoura, @lorenzejay, @nicoferdi96 + + + ## v1.12.0a3 diff --git a/docs/pt-BR/changelog.mdx b/docs/pt-BR/changelog.mdx index fd77840a8..18a27745c 100644 --- a/docs/pt-BR/changelog.mdx +++ b/docs/pt-BR/changelog.mdx @@ -4,6 +4,51 @@ description: "Atualizações de produto, melhorias e correções do CrewAI" icon: "clock" mode: "wide" --- + + ## v1.12.0 + + [Ver release no GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.12.0) + + ## O que Mudou + + ### Funcionalidades + - Adicionar backend de armazenamento Qdrant Edge para sistema de memória + - Adicionar comando docs-check para analisar mudanças e gerar documentos com traduções + - Adicionar suporte ao idioma árabe para changelog e ferramentas de lançamento + - Adicionar tradução em árabe padrão moderno de toda a documentação + - Adicionar comando de logout na CLI + - Implementar habilidades de agente + - Implementar root_scope automático para isolamento hierárquico de memória + - Implementar provedores nativos compatíveis com OpenAI (OpenRouter, DeepSeek, Ollama, vLLM, Cerebras, Dashscope) + + ### Correções de Bugs + - Corrigir credenciais inválidas para envio em lote de rastros (404) + - Resolver múltiplos bugs no sistema de fluxo HITL + - Resolver erros do mypy em crewai-files e adicionar todos os pacotes às verificações de tipo do CI + - Resolver todos os erros estritos do mypy no pacote crewai-tools + - Resolver todos os erros do mypy no pacote crewai + - Corrigir economia de memória no agente + - Corrigir uso de __router_paths__ para métodos listener+router em FlowMeta + - Levantar erro de valor em caso de suporte a arquivos inexistente + - Corrigir a redação da quarentena do litellm na documentação + - Usar verificação de None em vez de isinstance para memória no aprendizado de feedback humano + - Fixar limite superior do litellm na última versão testada (1.82.6) + + ### Documentação + - Atualizar changelog e versão para v1.12.0 + - Adicionar CONTRIBUTING.md + - Adicionar guia para usar CrewAI sem LiteLLM + + ### Refatoração + - Refatorar para desduplicar execução de tarefas síncronas/assíncronas e início no agente + - Simplificar a infraestrutura interna do litellm (contagem de tokens, callbacks, detecção de recursos, erros) + + ## Contribuidores + + @akaKuruma, @alex-clawd, @greysonlalonde, @iris-clawd, @joaomdmoura, @lorenzejay, @nicoferdi96 + + + ## v1.12.0a3 From 918654318b2fef9562bbbfc028c73eabe79c94fb Mon Sep 17 00:00:00 2001 From: Lucas Gomide Date: Wed, 25 Mar 2026 22:43:24 -0300 Subject: [PATCH 21/25] feat: add request_id to HumanFeedbackRequestedEvent (#5092) * feat: add request_id to HumanFeedbackRequestedEvent Allow platforms to attach a correlation identifier to human feedback requests so downstream consumers can deterministically match spans to their corresponding feedback records * feat: add request_id to HumanFeedbackReceivedEvent for correlation Without request_id on the received event, consumers cannot correlate a feedback response back to its originating request. Both sides of the request/response pair need the correlation identifier. --------- Co-authored-by: Alex --- lib/crewai/src/crewai/events/types/flow_events.py | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/lib/crewai/src/crewai/events/types/flow_events.py b/lib/crewai/src/crewai/events/types/flow_events.py index 3eea1bbdd..d820b8a05 100644 --- a/lib/crewai/src/crewai/events/types/flow_events.py +++ b/lib/crewai/src/crewai/events/types/flow_events.py @@ -178,12 +178,15 @@ class HumanFeedbackRequestedEvent(FlowEvent): output: The method output shown to the human for review. message: The message displayed when requesting feedback. emit: Optional list of possible outcomes for routing. + request_id: Platform-assigned identifier for this feedback request, + used for correlating the request across system boundaries. """ method_name: str output: Any message: str emit: list[str] | None = None + request_id: str | None = None type: str = "human_feedback_requested" @@ -198,9 +201,12 @@ class HumanFeedbackReceivedEvent(FlowEvent): method_name: Name of the method that received feedback. feedback: The raw text feedback provided by the human. outcome: The collapsed outcome string (if emit was specified). + request_id: Platform-assigned identifier for this feedback request, + used for correlating the response back to its originating request. """ method_name: str feedback: str outcome: str | None = None + request_id: str | None = None type: str = "human_feedback_received" From 034f576dc0d2d50ad7f0eefd14965653e343e1b0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jo=C3=A3o=20Moura?= Date: Wed, 25 Mar 2026 18:45:33 -0700 Subject: [PATCH 22/25] feat: bump versions to 1.12.1 (#5094) * chore: bump version to 1.12.1 across all modules * feat: bump versions to 1.12.1 --- lib/crewai-files/src/crewai_files/__init__.py | 2 +- lib/crewai-tools/pyproject.toml | 2 +- lib/crewai-tools/src/crewai_tools/__init__.py | 2 +- lib/crewai/pyproject.toml | 2 +- lib/crewai/src/crewai/__init__.py | 2 +- lib/crewai/src/crewai/cli/templates/crew/pyproject.toml | 2 +- lib/crewai/src/crewai/cli/templates/flow/pyproject.toml | 2 +- lib/crewai/src/crewai/cli/templates/tool/pyproject.toml | 2 +- lib/devtools/src/crewai_devtools/__init__.py | 2 +- 9 files changed, 9 insertions(+), 9 deletions(-) diff --git a/lib/crewai-files/src/crewai_files/__init__.py b/lib/crewai-files/src/crewai_files/__init__.py index 15f3af21f..58979f922 100644 --- a/lib/crewai-files/src/crewai_files/__init__.py +++ b/lib/crewai-files/src/crewai_files/__init__.py @@ -152,4 +152,4 @@ __all__ = [ "wrap_file_source", ] -__version__ = "1.12.0" +__version__ = "1.12.1" diff --git a/lib/crewai-tools/pyproject.toml b/lib/crewai-tools/pyproject.toml index 3c7ce1c7a..b73f8cde9 100644 --- a/lib/crewai-tools/pyproject.toml +++ b/lib/crewai-tools/pyproject.toml @@ -11,7 +11,7 @@ dependencies = [ "pytube~=15.0.0", "requests~=2.32.5", "docker~=7.1.0", - "crewai==1.12.0a3", + "crewai==1.12.1", "tiktoken~=0.8.0", "beautifulsoup4~=4.13.4", "python-docx~=1.2.0", diff --git a/lib/crewai-tools/src/crewai_tools/__init__.py b/lib/crewai-tools/src/crewai_tools/__init__.py index d2850a8b8..902aadf95 100644 --- a/lib/crewai-tools/src/crewai_tools/__init__.py +++ b/lib/crewai-tools/src/crewai_tools/__init__.py @@ -309,4 +309,4 @@ __all__ = [ "ZapierActionTools", ] -__version__ = "1.12.0" +__version__ = "1.12.1" diff --git a/lib/crewai/pyproject.toml b/lib/crewai/pyproject.toml index caeb6715c..b9060cf61 100644 --- a/lib/crewai/pyproject.toml +++ b/lib/crewai/pyproject.toml @@ -54,7 +54,7 @@ Repository = "https://github.com/crewAIInc/crewAI" [project.optional-dependencies] tools = [ - "crewai-tools==1.12.0a3", + "crewai-tools==1.12.1", ] embeddings = [ "tiktoken~=0.8.0" diff --git a/lib/crewai/src/crewai/__init__.py b/lib/crewai/src/crewai/__init__.py index f352b84e2..8b3577b88 100644 --- a/lib/crewai/src/crewai/__init__.py +++ b/lib/crewai/src/crewai/__init__.py @@ -42,7 +42,7 @@ def _suppress_pydantic_deprecation_warnings() -> None: _suppress_pydantic_deprecation_warnings() -__version__ = "1.12.0" +__version__ = "1.12.1" _telemetry_submitted = False diff --git a/lib/crewai/src/crewai/cli/templates/crew/pyproject.toml b/lib/crewai/src/crewai/cli/templates/crew/pyproject.toml index 0271a13fc..417f4ce92 100644 --- a/lib/crewai/src/crewai/cli/templates/crew/pyproject.toml +++ b/lib/crewai/src/crewai/cli/templates/crew/pyproject.toml @@ -5,7 +5,7 @@ description = "{{name}} using crewAI" authors = [{ name = "Your Name", email = "you@example.com" }] requires-python = ">=3.10,<3.14" dependencies = [ - "crewai[tools]==1.12.0a3" + "crewai[tools]==1.12.1" ] [project.scripts] diff --git a/lib/crewai/src/crewai/cli/templates/flow/pyproject.toml b/lib/crewai/src/crewai/cli/templates/flow/pyproject.toml index b3cfd338e..5790b4528 100644 --- a/lib/crewai/src/crewai/cli/templates/flow/pyproject.toml +++ b/lib/crewai/src/crewai/cli/templates/flow/pyproject.toml @@ -5,7 +5,7 @@ description = "{{name}} using crewAI" authors = [{ name = "Your Name", email = "you@example.com" }] requires-python = ">=3.10,<3.14" dependencies = [ - "crewai[tools]==1.12.0a3" + "crewai[tools]==1.12.1" ] [project.scripts] diff --git a/lib/crewai/src/crewai/cli/templates/tool/pyproject.toml b/lib/crewai/src/crewai/cli/templates/tool/pyproject.toml index 9a549f520..ca2243815 100644 --- a/lib/crewai/src/crewai/cli/templates/tool/pyproject.toml +++ b/lib/crewai/src/crewai/cli/templates/tool/pyproject.toml @@ -5,7 +5,7 @@ description = "Power up your crews with {{folder_name}}" readme = "README.md" requires-python = ">=3.10,<3.14" dependencies = [ - "crewai[tools]==1.12.0a3" + "crewai[tools]==1.12.1" ] [tool.crewai] diff --git a/lib/devtools/src/crewai_devtools/__init__.py b/lib/devtools/src/crewai_devtools/__init__.py index ac5ed2ca5..4cb918542 100644 --- a/lib/devtools/src/crewai_devtools/__init__.py +++ b/lib/devtools/src/crewai_devtools/__init__.py @@ -1,3 +1,3 @@ """CrewAI development tools.""" -__version__ = "1.12.0" +__version__ = "1.12.1" From 66dee3195f68c4fd6991b59672e5750f6d5f41e0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Jo=C3=A3o=20Moura?= Date: Wed, 25 Mar 2026 18:52:11 -0700 Subject: [PATCH 23/25] docs: update changelog and version for v1.12.1 (#5095) --- docs/ar/changelog.mdx | 40 + docs/docs.json | 1863 +++++++++++++++++++++++++++++++++++++- docs/en/changelog.mdx | 40 + docs/ko/changelog.mdx | 40 + docs/pt-BR/changelog.mdx | 40 + 5 files changed, 2019 insertions(+), 4 deletions(-) diff --git a/docs/ar/changelog.mdx b/docs/ar/changelog.mdx index 6137596f0..296f4cbdf 100644 --- a/docs/ar/changelog.mdx +++ b/docs/ar/changelog.mdx @@ -4,6 +4,46 @@ description: "تحديثات المنتج والتحسينات وإصلاحات icon: "clock" mode: "wide" --- + + ## 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 diff --git a/docs/docs.json b/docs/docs.json index 7f1e03e37..e3f96ff63 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -56,7 +56,7 @@ }, "versions": [ { - "version": "v1.12.0", + "version": "v1.12.1", "default": true, "tabs": [ { @@ -525,6 +525,475 @@ } ] }, + { + "version": "v1.12.0", + "tabs": [ + { + "tab": "Home", + "icon": "house", + "groups": [ + { + "group": "Welcome", + "pages": [ + "index" + ] + } + ] + }, + { + "tab": "Documentation", + "icon": "book-open", + "groups": [ + { + "group": "Get Started", + "pages": [ + "en/introduction", + "en/installation", + "en/quickstart" + ] + }, + { + "group": "Guides", + "pages": [ + { + "group": "Strategy", + "icon": "compass", + "pages": [ + "en/guides/concepts/evaluating-use-cases" + ] + }, + { + "group": "Agents", + "icon": "user", + "pages": [ + "en/guides/agents/crafting-effective-agents" + ] + }, + { + "group": "Crews", + "icon": "users", + "pages": [ + "en/guides/crews/first-crew" + ] + }, + { + "group": "Flows", + "icon": "code-branch", + "pages": [ + "en/guides/flows/first-flow", + "en/guides/flows/mastering-flow-state" + ] + }, + { + "group": "Tools", + "icon": "wrench", + "pages": [ + "en/guides/tools/publish-custom-tools" + ] + }, + { + "group": "Coding Tools", + "icon": "terminal", + "pages": [ + "en/guides/coding-tools/agents-md" + ] + }, + { + "group": "Advanced", + "icon": "gear", + "pages": [ + "en/guides/advanced/customizing-prompts", + "en/guides/advanced/fingerprinting" + ] + }, + { + "group": "Migration", + "icon": "shuffle", + "pages": [ + "en/guides/migration/migrating-from-langgraph" + ] + } + ] + }, + { + "group": "Core Concepts", + "pages": [ + "en/concepts/agents", + "en/concepts/tasks", + "en/concepts/crews", + "en/concepts/flows", + "en/concepts/production-architecture", + "en/concepts/knowledge", + "en/concepts/skills", + "en/concepts/llms", + "en/concepts/files", + "en/concepts/processes", + "en/concepts/collaboration", + "en/concepts/training", + "en/concepts/memory", + "en/concepts/reasoning", + "en/concepts/planning", + "en/concepts/testing", + "en/concepts/cli", + "en/concepts/tools", + "en/concepts/event-listener" + ] + }, + { + "group": "MCP Integration", + "pages": [ + "en/mcp/overview", + "en/mcp/dsl-integration", + "en/mcp/stdio", + "en/mcp/sse", + "en/mcp/streamable-http", + "en/mcp/multiple-servers", + "en/mcp/security" + ] + }, + { + "group": "Tools", + "pages": [ + "en/tools/overview", + { + "group": "File & Document", + "icon": "folder-open", + "pages": [ + "en/tools/file-document/overview", + "en/tools/file-document/filereadtool", + "en/tools/file-document/filewritetool", + "en/tools/file-document/pdfsearchtool", + "en/tools/file-document/docxsearchtool", + "en/tools/file-document/mdxsearchtool", + "en/tools/file-document/xmlsearchtool", + "en/tools/file-document/txtsearchtool", + "en/tools/file-document/jsonsearchtool", + "en/tools/file-document/csvsearchtool", + "en/tools/file-document/directorysearchtool", + "en/tools/file-document/directoryreadtool", + "en/tools/file-document/ocrtool", + "en/tools/file-document/pdf-text-writing-tool" + ] + }, + { + "group": "Web Scraping & Browsing", + "icon": "globe", + "pages": [ + "en/tools/web-scraping/overview", + "en/tools/web-scraping/scrapewebsitetool", + "en/tools/web-scraping/scrapeelementfromwebsitetool", + "en/tools/web-scraping/scrapflyscrapetool", + "en/tools/web-scraping/seleniumscrapingtool", + "en/tools/web-scraping/scrapegraphscrapetool", + "en/tools/web-scraping/spidertool", + "en/tools/web-scraping/browserbaseloadtool", + "en/tools/web-scraping/hyperbrowserloadtool", + "en/tools/web-scraping/stagehandtool", + "en/tools/web-scraping/firecrawlcrawlwebsitetool", + "en/tools/web-scraping/firecrawlscrapewebsitetool", + "en/tools/web-scraping/oxylabsscraperstool", + "en/tools/web-scraping/brightdata-tools" + ] + }, + { + "group": "Search & Research", + "icon": "magnifying-glass", + "pages": [ + "en/tools/search-research/overview", + "en/tools/search-research/serperdevtool", + "en/tools/search-research/bravesearchtool", + "en/tools/search-research/exasearchtool", + "en/tools/search-research/linkupsearchtool", + "en/tools/search-research/githubsearchtool", + "en/tools/search-research/websitesearchtool", + "en/tools/search-research/codedocssearchtool", + "en/tools/search-research/youtubechannelsearchtool", + "en/tools/search-research/youtubevideosearchtool", + "en/tools/search-research/tavilysearchtool", + "en/tools/search-research/tavilyextractortool", + "en/tools/search-research/arxivpapertool", + "en/tools/search-research/serpapi-googlesearchtool", + "en/tools/search-research/serpapi-googleshoppingtool", + "en/tools/search-research/databricks-query-tool" + ] + }, + { + "group": "Database & Data", + "icon": "database", + "pages": [ + "en/tools/database-data/overview", + "en/tools/database-data/mysqltool", + "en/tools/database-data/pgsearchtool", + "en/tools/database-data/snowflakesearchtool", + "en/tools/database-data/nl2sqltool", + "en/tools/database-data/qdrantvectorsearchtool", + "en/tools/database-data/weaviatevectorsearchtool", + "en/tools/database-data/mongodbvectorsearchtool", + "en/tools/database-data/singlestoresearchtool" + ] + }, + { + "group": "AI & Machine Learning", + "icon": "brain", + "pages": [ + "en/tools/ai-ml/overview", + "en/tools/ai-ml/dalletool", + "en/tools/ai-ml/visiontool", + "en/tools/ai-ml/aimindtool", + "en/tools/ai-ml/llamaindextool", + "en/tools/ai-ml/langchaintool", + "en/tools/ai-ml/ragtool", + "en/tools/ai-ml/codeinterpretertool" + ] + }, + { + "group": "Cloud & Storage", + "icon": "cloud", + "pages": [ + "en/tools/cloud-storage/overview", + "en/tools/cloud-storage/s3readertool", + "en/tools/cloud-storage/s3writertool", + "en/tools/cloud-storage/bedrockkbretriever" + ] + }, + { + "group": "Integrations", + "icon": "plug", + "pages": [ + "en/tools/integration/overview", + "en/tools/integration/bedrockinvokeagenttool", + "en/tools/integration/crewaiautomationtool", + "en/tools/integration/mergeagenthandlertool" + ] + }, + { + "group": "Automation", + "icon": "bolt", + "pages": [ + "en/tools/automation/overview", + "en/tools/automation/apifyactorstool", + "en/tools/automation/composiotool", + "en/tools/automation/multiontool", + "en/tools/automation/zapieractionstool" + ] + } + ] + }, + { + "group": "Observability", + "pages": [ + "en/observability/tracing", + "en/observability/overview", + "en/observability/arize-phoenix", + "en/observability/braintrust", + "en/observability/datadog", + "en/observability/galileo", + "en/observability/langdb", + "en/observability/langfuse", + "en/observability/langtrace", + "en/observability/maxim", + "en/observability/mlflow", + "en/observability/neatlogs", + "en/observability/openlit", + "en/observability/opik", + "en/observability/patronus-evaluation", + "en/observability/portkey", + "en/observability/weave", + "en/observability/truefoundry" + ] + }, + { + "group": "Learn", + "pages": [ + "en/learn/overview", + "en/learn/llm-selection-guide", + "en/learn/conditional-tasks", + "en/learn/coding-agents", + "en/learn/create-custom-tools", + "en/learn/custom-llm", + "en/learn/custom-manager-agent", + "en/learn/customizing-agents", + "en/learn/dalle-image-generation", + "en/learn/force-tool-output-as-result", + "en/learn/hierarchical-process", + "en/learn/human-input-on-execution", + "en/learn/human-in-the-loop", + "en/learn/human-feedback-in-flows", + "en/learn/kickoff-async", + "en/learn/kickoff-for-each", + "en/learn/llm-connections", + "en/learn/litellm-removal-guide", + "en/learn/multimodal-agents", + "en/learn/replay-tasks-from-latest-crew-kickoff", + "en/learn/sequential-process", + "en/learn/using-annotations", + "en/learn/execution-hooks", + "en/learn/llm-hooks", + "en/learn/tool-hooks" + ] + }, + { + "group": "Telemetry", + "pages": [ + "en/telemetry" + ] + } + ] + }, + { + "tab": "AMP", + "icon": "briefcase", + "groups": [ + { + "group": "Getting Started", + "pages": [ + "en/enterprise/introduction" + ] + }, + { + "group": "Build", + "pages": [ + "en/enterprise/features/automations", + "en/enterprise/features/crew-studio", + "en/enterprise/features/marketplace", + "en/enterprise/features/agent-repositories", + "en/enterprise/features/tools-and-integrations", + "en/enterprise/features/pii-trace-redactions" + ] + }, + { + "group": "Operate", + "pages": [ + "en/enterprise/features/traces", + "en/enterprise/features/webhook-streaming", + "en/enterprise/features/hallucination-guardrail", + "en/enterprise/features/flow-hitl-management" + ] + }, + { + "group": "Manage", + "pages": [ + "en/enterprise/features/rbac" + ] + }, + { + "group": "Integration Docs", + "pages": [ + "en/enterprise/integrations/asana", + "en/enterprise/integrations/box", + "en/enterprise/integrations/clickup", + "en/enterprise/integrations/github", + "en/enterprise/integrations/gmail", + "en/enterprise/integrations/google_calendar", + "en/enterprise/integrations/google_contacts", + "en/enterprise/integrations/google_docs", + "en/enterprise/integrations/google_drive", + "en/enterprise/integrations/google_sheets", + "en/enterprise/integrations/google_slides", + "en/enterprise/integrations/hubspot", + "en/enterprise/integrations/jira", + "en/enterprise/integrations/linear", + "en/enterprise/integrations/microsoft_excel", + "en/enterprise/integrations/microsoft_onedrive", + "en/enterprise/integrations/microsoft_outlook", + "en/enterprise/integrations/microsoft_sharepoint", + "en/enterprise/integrations/microsoft_teams", + "en/enterprise/integrations/microsoft_word", + "en/enterprise/integrations/notion", + "en/enterprise/integrations/salesforce", + "en/enterprise/integrations/shopify", + "en/enterprise/integrations/slack", + "en/enterprise/integrations/stripe", + "en/enterprise/integrations/zendesk" + ] + }, + { + "group": "Triggers", + "pages": [ + "en/enterprise/guides/automation-triggers", + "en/enterprise/guides/gmail-trigger", + "en/enterprise/guides/google-calendar-trigger", + "en/enterprise/guides/google-drive-trigger", + "en/enterprise/guides/outlook-trigger", + "en/enterprise/guides/onedrive-trigger", + "en/enterprise/guides/microsoft-teams-trigger", + "en/enterprise/guides/slack-trigger", + "en/enterprise/guides/hubspot-trigger", + "en/enterprise/guides/salesforce-trigger", + "en/enterprise/guides/zapier-trigger" + ] + }, + { + "group": "How-To Guides", + "pages": [ + "en/enterprise/guides/build-crew", + "en/enterprise/guides/prepare-for-deployment", + "en/enterprise/guides/deploy-to-amp", + "en/enterprise/guides/private-package-registry", + "en/enterprise/guides/kickoff-crew", + "en/enterprise/guides/update-crew", + "en/enterprise/guides/enable-crew-studio", + "en/enterprise/guides/capture_telemetry_logs", + "en/enterprise/guides/azure-openai-setup", + "en/enterprise/guides/tool-repository", + "en/enterprise/guides/custom-mcp-server", + "en/enterprise/guides/react-component-export", + "en/enterprise/guides/team-management", + "en/enterprise/guides/human-in-the-loop", + "en/enterprise/guides/webhook-automation" + ] + }, + { + "group": "Resources", + "pages": [ + "en/enterprise/resources/frequently-asked-questions" + ] + } + ] + }, + { + "tab": "API Reference", + "icon": "magnifying-glass", + "groups": [ + { + "group": "Getting Started", + "pages": [ + "en/api-reference/introduction", + "en/api-reference/inputs", + "en/api-reference/kickoff", + "en/api-reference/resume", + "en/api-reference/status" + ] + } + ] + }, + { + "tab": "Examples", + "icon": "code", + "groups": [ + { + "group": "Examples", + "pages": [ + "en/examples/example", + "en/examples/cookbooks" + ] + } + ] + }, + { + "tab": "Changelog", + "icon": "clock", + "groups": [ + { + "group": "Release Notes", + "pages": [ + "en/changelog" + ] + } + ] + } + ] + }, { "version": "v1.11.1", "tabs": [ @@ -2429,7 +2898,7 @@ }, "versions": [ { - "version": "v1.12.0", + "version": "v1.12.1", "default": true, "tabs": [ { @@ -2883,6 +3352,460 @@ } ] }, + { + "version": "v1.12.0", + "tabs": [ + { + "tab": "Início", + "icon": "house", + "groups": [ + { + "group": "Bem-vindo", + "pages": [ + "pt-BR/index" + ] + } + ] + }, + { + "tab": "Documentação", + "icon": "book-open", + "groups": [ + { + "group": "Começando", + "pages": [ + "pt-BR/introduction", + "pt-BR/installation", + "pt-BR/quickstart" + ] + }, + { + "group": "Guias", + "pages": [ + { + "group": "Estratégia", + "icon": "compass", + "pages": [ + "pt-BR/guides/concepts/evaluating-use-cases" + ] + }, + { + "group": "Agentes", + "icon": "user", + "pages": [ + "pt-BR/guides/agents/crafting-effective-agents" + ] + }, + { + "group": "Crews", + "icon": "users", + "pages": [ + "pt-BR/guides/crews/first-crew" + ] + }, + { + "group": "Flows", + "icon": "code-branch", + "pages": [ + "pt-BR/guides/flows/first-flow", + "pt-BR/guides/flows/mastering-flow-state" + ] + }, + { + "group": "Ferramentas", + "icon": "wrench", + "pages": [ + "pt-BR/guides/tools/publish-custom-tools" + ] + }, + { + "group": "Ferramentas de Codificação", + "icon": "terminal", + "pages": [ + "pt-BR/guides/coding-tools/agents-md" + ] + }, + { + "group": "Avançado", + "icon": "gear", + "pages": [ + "pt-BR/guides/advanced/customizing-prompts", + "pt-BR/guides/advanced/fingerprinting" + ] + }, + { + "group": "Migração", + "icon": "shuffle", + "pages": [ + "pt-BR/guides/migration/migrating-from-langgraph" + ] + } + ] + }, + { + "group": "Conceitos-Chave", + "pages": [ + "pt-BR/concepts/agents", + "pt-BR/concepts/tasks", + "pt-BR/concepts/crews", + "pt-BR/concepts/flows", + "pt-BR/concepts/production-architecture", + "pt-BR/concepts/knowledge", + "pt-BR/concepts/skills", + "pt-BR/concepts/llms", + "pt-BR/concepts/files", + "pt-BR/concepts/processes", + "pt-BR/concepts/collaboration", + "pt-BR/concepts/training", + "pt-BR/concepts/memory", + "pt-BR/concepts/reasoning", + "pt-BR/concepts/planning", + "pt-BR/concepts/testing", + "pt-BR/concepts/cli", + "pt-BR/concepts/tools", + "pt-BR/concepts/event-listener" + ] + }, + { + "group": "Integração MCP", + "pages": [ + "pt-BR/mcp/overview", + "pt-BR/mcp/dsl-integration", + "pt-BR/mcp/stdio", + "pt-BR/mcp/sse", + "pt-BR/mcp/streamable-http", + "pt-BR/mcp/multiple-servers", + "pt-BR/mcp/security" + ] + }, + { + "group": "Ferramentas", + "pages": [ + "pt-BR/tools/overview", + { + "group": "Arquivo & Documento", + "icon": "folder-open", + "pages": [ + "pt-BR/tools/file-document/overview", + "pt-BR/tools/file-document/filereadtool", + "pt-BR/tools/file-document/filewritetool", + "pt-BR/tools/file-document/pdfsearchtool", + "pt-BR/tools/file-document/docxsearchtool", + "pt-BR/tools/file-document/mdxsearchtool", + "pt-BR/tools/file-document/xmlsearchtool", + "pt-BR/tools/file-document/txtsearchtool", + "pt-BR/tools/file-document/jsonsearchtool", + "pt-BR/tools/file-document/csvsearchtool", + "pt-BR/tools/file-document/directorysearchtool", + "pt-BR/tools/file-document/directoryreadtool" + ] + }, + { + "group": "Web Scraping & Navegação", + "icon": "globe", + "pages": [ + "pt-BR/tools/web-scraping/overview", + "pt-BR/tools/web-scraping/scrapewebsitetool", + "pt-BR/tools/web-scraping/scrapeelementfromwebsitetool", + "pt-BR/tools/web-scraping/scrapflyscrapetool", + "pt-BR/tools/web-scraping/seleniumscrapingtool", + "pt-BR/tools/web-scraping/scrapegraphscrapetool", + "pt-BR/tools/web-scraping/spidertool", + "pt-BR/tools/web-scraping/browserbaseloadtool", + "pt-BR/tools/web-scraping/hyperbrowserloadtool", + "pt-BR/tools/web-scraping/stagehandtool", + "pt-BR/tools/web-scraping/firecrawlcrawlwebsitetool", + "pt-BR/tools/web-scraping/firecrawlscrapewebsitetool", + "pt-BR/tools/web-scraping/oxylabsscraperstool" + ] + }, + { + "group": "Pesquisa", + "icon": "magnifying-glass", + "pages": [ + "pt-BR/tools/search-research/overview", + "pt-BR/tools/search-research/serperdevtool", + "pt-BR/tools/search-research/bravesearchtool", + "pt-BR/tools/search-research/exasearchtool", + "pt-BR/tools/search-research/linkupsearchtool", + "pt-BR/tools/search-research/githubsearchtool", + "pt-BR/tools/search-research/websitesearchtool", + "pt-BR/tools/search-research/codedocssearchtool", + "pt-BR/tools/search-research/youtubechannelsearchtool", + "pt-BR/tools/search-research/youtubevideosearchtool" + ] + }, + { + "group": "Dados", + "icon": "database", + "pages": [ + "pt-BR/tools/database-data/overview", + "pt-BR/tools/database-data/mysqltool", + "pt-BR/tools/database-data/pgsearchtool", + "pt-BR/tools/database-data/snowflakesearchtool", + "pt-BR/tools/database-data/nl2sqltool", + "pt-BR/tools/database-data/qdrantvectorsearchtool", + "pt-BR/tools/database-data/weaviatevectorsearchtool" + ] + }, + { + "group": "IA & Machine Learning", + "icon": "brain", + "pages": [ + "pt-BR/tools/ai-ml/overview", + "pt-BR/tools/ai-ml/dalletool", + "pt-BR/tools/ai-ml/visiontool", + "pt-BR/tools/ai-ml/aimindtool", + "pt-BR/tools/ai-ml/llamaindextool", + "pt-BR/tools/ai-ml/langchaintool", + "pt-BR/tools/ai-ml/ragtool", + "pt-BR/tools/ai-ml/codeinterpretertool" + ] + }, + { + "group": "Cloud & Armazenamento", + "icon": "cloud", + "pages": [ + "pt-BR/tools/cloud-storage/overview", + "pt-BR/tools/cloud-storage/s3readertool", + "pt-BR/tools/cloud-storage/s3writertool", + "pt-BR/tools/cloud-storage/bedrockkbretriever" + ] + }, + { + "group": "Integrations", + "icon": "plug", + "pages": [ + "pt-BR/tools/integration/overview", + "pt-BR/tools/integration/bedrockinvokeagenttool", + "pt-BR/tools/integration/crewaiautomationtool" + ] + }, + { + "group": "Automação", + "icon": "bolt", + "pages": [ + "pt-BR/tools/automation/overview", + "pt-BR/tools/automation/apifyactorstool", + "pt-BR/tools/automation/composiotool", + "pt-BR/tools/automation/multiontool" + ] + } + ] + }, + { + "group": "Observabilidade", + "pages": [ + "pt-BR/observability/tracing", + "pt-BR/observability/overview", + "pt-BR/observability/arize-phoenix", + "pt-BR/observability/braintrust", + "pt-BR/observability/datadog", + "pt-BR/observability/galileo", + "pt-BR/observability/langdb", + "pt-BR/observability/langfuse", + "pt-BR/observability/langtrace", + "pt-BR/observability/maxim", + "pt-BR/observability/mlflow", + "pt-BR/observability/openlit", + "pt-BR/observability/opik", + "pt-BR/observability/patronus-evaluation", + "pt-BR/observability/portkey", + "pt-BR/observability/weave", + "pt-BR/observability/truefoundry" + ] + }, + { + "group": "Aprenda", + "pages": [ + "pt-BR/learn/overview", + "pt-BR/learn/llm-selection-guide", + "pt-BR/learn/conditional-tasks", + "pt-BR/learn/coding-agents", + "pt-BR/learn/create-custom-tools", + "pt-BR/learn/custom-llm", + "pt-BR/learn/custom-manager-agent", + "pt-BR/learn/customizing-agents", + "pt-BR/learn/dalle-image-generation", + "pt-BR/learn/force-tool-output-as-result", + "pt-BR/learn/hierarchical-process", + "pt-BR/learn/human-input-on-execution", + "pt-BR/learn/human-in-the-loop", + "pt-BR/learn/human-feedback-in-flows", + "pt-BR/learn/kickoff-async", + "pt-BR/learn/kickoff-for-each", + "pt-BR/learn/llm-connections", + "pt-BR/learn/multimodal-agents", + "pt-BR/learn/replay-tasks-from-latest-crew-kickoff", + "pt-BR/learn/sequential-process", + "pt-BR/learn/using-annotations", + "pt-BR/learn/execution-hooks", + "pt-BR/learn/llm-hooks", + "pt-BR/learn/tool-hooks" + ] + }, + { + "group": "Telemetria", + "pages": [ + "pt-BR/telemetry" + ] + } + ] + }, + { + "tab": "AMP", + "icon": "briefcase", + "groups": [ + { + "group": "Começando", + "pages": [ + "pt-BR/enterprise/introduction" + ] + }, + { + "group": "Construir", + "pages": [ + "pt-BR/enterprise/features/automations", + "pt-BR/enterprise/features/crew-studio", + "pt-BR/enterprise/features/marketplace", + "pt-BR/enterprise/features/agent-repositories", + "pt-BR/enterprise/features/tools-and-integrations", + "pt-BR/enterprise/features/pii-trace-redactions" + ] + }, + { + "group": "Operar", + "pages": [ + "pt-BR/enterprise/features/traces", + "pt-BR/enterprise/features/webhook-streaming", + "pt-BR/enterprise/features/hallucination-guardrail", + "pt-BR/enterprise/features/flow-hitl-management" + ] + }, + { + "group": "Gerenciar", + "pages": [ + "pt-BR/enterprise/features/rbac" + ] + }, + { + "group": "Documentação de Integração", + "pages": [ + "pt-BR/enterprise/integrations/asana", + "pt-BR/enterprise/integrations/box", + "pt-BR/enterprise/integrations/clickup", + "pt-BR/enterprise/integrations/github", + "pt-BR/enterprise/integrations/gmail", + "pt-BR/enterprise/integrations/google_calendar", + "pt-BR/enterprise/integrations/google_contacts", + "pt-BR/enterprise/integrations/google_docs", + "pt-BR/enterprise/integrations/google_drive", + "pt-BR/enterprise/integrations/google_sheets", + "pt-BR/enterprise/integrations/google_slides", + "pt-BR/enterprise/integrations/hubspot", + "pt-BR/enterprise/integrations/jira", + "pt-BR/enterprise/integrations/linear", + "pt-BR/enterprise/integrations/microsoft_excel", + "pt-BR/enterprise/integrations/microsoft_onedrive", + "pt-BR/enterprise/integrations/microsoft_outlook", + "pt-BR/enterprise/integrations/microsoft_sharepoint", + "pt-BR/enterprise/integrations/microsoft_teams", + "pt-BR/enterprise/integrations/microsoft_word", + "pt-BR/enterprise/integrations/notion", + "pt-BR/enterprise/integrations/salesforce", + "pt-BR/enterprise/integrations/shopify", + "pt-BR/enterprise/integrations/slack", + "pt-BR/enterprise/integrations/stripe", + "pt-BR/enterprise/integrations/zendesk" + ] + }, + { + "group": "Guias", + "pages": [ + "pt-BR/enterprise/guides/build-crew", + "pt-BR/enterprise/guides/prepare-for-deployment", + "pt-BR/enterprise/guides/deploy-to-amp", + "pt-BR/enterprise/guides/private-package-registry", + "pt-BR/enterprise/guides/kickoff-crew", + "pt-BR/enterprise/guides/update-crew", + "pt-BR/enterprise/guides/enable-crew-studio", + "pt-BR/enterprise/guides/capture_telemetry_logs", + "pt-BR/enterprise/guides/azure-openai-setup", + "pt-BR/enterprise/guides/tool-repository", + "pt-BR/enterprise/guides/custom-mcp-server", + "pt-BR/enterprise/guides/react-component-export", + "pt-BR/enterprise/guides/team-management", + "pt-BR/enterprise/guides/human-in-the-loop", + "pt-BR/enterprise/guides/webhook-automation" + ] + }, + { + "group": "Triggers", + "pages": [ + "pt-BR/enterprise/guides/automation-triggers", + "pt-BR/enterprise/guides/gmail-trigger", + "pt-BR/enterprise/guides/google-calendar-trigger", + "pt-BR/enterprise/guides/google-drive-trigger", + "pt-BR/enterprise/guides/outlook-trigger", + "pt-BR/enterprise/guides/onedrive-trigger", + "pt-BR/enterprise/guides/microsoft-teams-trigger", + "pt-BR/enterprise/guides/slack-trigger", + "pt-BR/enterprise/guides/hubspot-trigger", + "pt-BR/enterprise/guides/salesforce-trigger", + "pt-BR/enterprise/guides/zapier-trigger" + ] + }, + { + "group": "Recursos", + "pages": [ + "pt-BR/enterprise/resources/frequently-asked-questions" + ] + } + ] + }, + { + "tab": "Referência da API", + "icon": "magnifying-glass", + "groups": [ + { + "group": "Começando", + "pages": [ + "pt-BR/api-reference/introduction", + "pt-BR/api-reference/inputs", + "pt-BR/api-reference/kickoff", + "pt-BR/api-reference/resume", + "pt-BR/api-reference/status" + ] + } + ] + }, + { + "tab": "Exemplos", + "icon": "code", + "groups": [ + { + "group": "Exemplos", + "pages": [ + "pt-BR/examples/example", + "pt-BR/examples/cookbooks" + ] + } + ] + }, + { + "tab": "Notas de Versão", + "icon": "clock", + "groups": [ + { + "group": "Notas de Versão", + "pages": [ + "pt-BR/changelog" + ] + } + ] + } + ] + }, { "version": "v1.11.1", "tabs": [ @@ -4727,7 +5650,7 @@ }, "versions": [ { - "version": "v1.12.0", + "version": "v1.12.1", "default": true, "tabs": [ { @@ -5193,6 +6116,472 @@ } ] }, + { + "version": "v1.12.0", + "tabs": [ + { + "tab": "홈", + "icon": "house", + "groups": [ + { + "group": "환영합니다", + "pages": [ + "ko/index" + ] + } + ] + }, + { + "tab": "기술 문서", + "icon": "book-open", + "groups": [ + { + "group": "시작 안내", + "pages": [ + "ko/introduction", + "ko/installation", + "ko/quickstart" + ] + }, + { + "group": "가이드", + "pages": [ + { + "group": "전략", + "icon": "compass", + "pages": [ + "ko/guides/concepts/evaluating-use-cases" + ] + }, + { + "group": "에이전트 (Agents)", + "icon": "user", + "pages": [ + "ko/guides/agents/crafting-effective-agents" + ] + }, + { + "group": "크루 (Crews)", + "icon": "users", + "pages": [ + "ko/guides/crews/first-crew" + ] + }, + { + "group": "플로우 (Flows)", + "icon": "code-branch", + "pages": [ + "ko/guides/flows/first-flow", + "ko/guides/flows/mastering-flow-state" + ] + }, + { + "group": "도구", + "icon": "wrench", + "pages": [ + "ko/guides/tools/publish-custom-tools" + ] + }, + { + "group": "코딩 도구", + "icon": "terminal", + "pages": [ + "ko/guides/coding-tools/agents-md" + ] + }, + { + "group": "고급", + "icon": "gear", + "pages": [ + "ko/guides/advanced/customizing-prompts", + "ko/guides/advanced/fingerprinting" + ] + }, + { + "group": "마이그레이션", + "icon": "shuffle", + "pages": [ + "ko/guides/migration/migrating-from-langgraph" + ] + } + ] + }, + { + "group": "핵심 개념", + "pages": [ + "ko/concepts/agents", + "ko/concepts/tasks", + "ko/concepts/crews", + "ko/concepts/flows", + "ko/concepts/production-architecture", + "ko/concepts/knowledge", + "ko/concepts/skills", + "ko/concepts/llms", + "ko/concepts/files", + "ko/concepts/processes", + "ko/concepts/collaboration", + "ko/concepts/training", + "ko/concepts/memory", + "ko/concepts/reasoning", + "ko/concepts/planning", + "ko/concepts/testing", + "ko/concepts/cli", + "ko/concepts/tools", + "ko/concepts/event-listener" + ] + }, + { + "group": "MCP 통합", + "pages": [ + "ko/mcp/overview", + "ko/mcp/dsl-integration", + "ko/mcp/stdio", + "ko/mcp/sse", + "ko/mcp/streamable-http", + "ko/mcp/multiple-servers", + "ko/mcp/security" + ] + }, + { + "group": "도구 (Tools)", + "pages": [ + "ko/tools/overview", + { + "group": "파일 & 문서", + "icon": "folder-open", + "pages": [ + "ko/tools/file-document/overview", + "ko/tools/file-document/filereadtool", + "ko/tools/file-document/filewritetool", + "ko/tools/file-document/pdfsearchtool", + "ko/tools/file-document/docxsearchtool", + "ko/tools/file-document/mdxsearchtool", + "ko/tools/file-document/xmlsearchtool", + "ko/tools/file-document/txtsearchtool", + "ko/tools/file-document/jsonsearchtool", + "ko/tools/file-document/csvsearchtool", + "ko/tools/file-document/directorysearchtool", + "ko/tools/file-document/directoryreadtool", + "ko/tools/file-document/ocrtool", + "ko/tools/file-document/pdf-text-writing-tool" + ] + }, + { + "group": "웹 스크래핑 & 브라우징", + "icon": "globe", + "pages": [ + "ko/tools/web-scraping/overview", + "ko/tools/web-scraping/scrapewebsitetool", + "ko/tools/web-scraping/scrapeelementfromwebsitetool", + "ko/tools/web-scraping/scrapflyscrapetool", + "ko/tools/web-scraping/seleniumscrapingtool", + "ko/tools/web-scraping/scrapegraphscrapetool", + "ko/tools/web-scraping/spidertool", + "ko/tools/web-scraping/browserbaseloadtool", + "ko/tools/web-scraping/hyperbrowserloadtool", + "ko/tools/web-scraping/stagehandtool", + "ko/tools/web-scraping/firecrawlcrawlwebsitetool", + "ko/tools/web-scraping/firecrawlscrapewebsitetool", + "ko/tools/web-scraping/oxylabsscraperstool", + "ko/tools/web-scraping/brightdata-tools" + ] + }, + { + "group": "검색 및 연구", + "icon": "magnifying-glass", + "pages": [ + "ko/tools/search-research/overview", + "ko/tools/search-research/serperdevtool", + "ko/tools/search-research/bravesearchtool", + "ko/tools/search-research/exasearchtool", + "ko/tools/search-research/linkupsearchtool", + "ko/tools/search-research/githubsearchtool", + "ko/tools/search-research/websitesearchtool", + "ko/tools/search-research/codedocssearchtool", + "ko/tools/search-research/youtubechannelsearchtool", + "ko/tools/search-research/youtubevideosearchtool", + "ko/tools/search-research/tavilysearchtool", + "ko/tools/search-research/tavilyextractortool", + "ko/tools/search-research/arxivpapertool", + "ko/tools/search-research/serpapi-googlesearchtool", + "ko/tools/search-research/serpapi-googleshoppingtool", + "ko/tools/search-research/databricks-query-tool" + ] + }, + { + "group": "데이터베이스 & 데이터", + "icon": "database", + "pages": [ + "ko/tools/database-data/overview", + "ko/tools/database-data/mysqltool", + "ko/tools/database-data/pgsearchtool", + "ko/tools/database-data/snowflakesearchtool", + "ko/tools/database-data/nl2sqltool", + "ko/tools/database-data/qdrantvectorsearchtool", + "ko/tools/database-data/weaviatevectorsearchtool", + "ko/tools/database-data/mongodbvectorsearchtool", + "ko/tools/database-data/singlestoresearchtool" + ] + }, + { + "group": "인공지능 & 머신러닝", + "icon": "brain", + "pages": [ + "ko/tools/ai-ml/overview", + "ko/tools/ai-ml/dalletool", + "ko/tools/ai-ml/visiontool", + "ko/tools/ai-ml/aimindtool", + "ko/tools/ai-ml/llamaindextool", + "ko/tools/ai-ml/langchaintool", + "ko/tools/ai-ml/ragtool", + "ko/tools/ai-ml/codeinterpretertool" + ] + }, + { + "group": "클라우드 & 스토리지", + "icon": "cloud", + "pages": [ + "ko/tools/cloud-storage/overview", + "ko/tools/cloud-storage/s3readertool", + "ko/tools/cloud-storage/s3writertool", + "ko/tools/cloud-storage/bedrockkbretriever" + ] + }, + { + "group": "Integrations", + "icon": "plug", + "pages": [ + "ko/tools/integration/overview", + "ko/tools/integration/bedrockinvokeagenttool", + "ko/tools/integration/crewaiautomationtool" + ] + }, + { + "group": "자동화", + "icon": "bolt", + "pages": [ + "ko/tools/automation/overview", + "ko/tools/automation/apifyactorstool", + "ko/tools/automation/composiotool", + "ko/tools/automation/multiontool", + "ko/tools/automation/zapieractionstool" + ] + } + ] + }, + { + "group": "Observability", + "pages": [ + "ko/observability/tracing", + "ko/observability/overview", + "ko/observability/arize-phoenix", + "ko/observability/braintrust", + "ko/observability/datadog", + "ko/observability/galileo", + "ko/observability/langdb", + "ko/observability/langfuse", + "ko/observability/langtrace", + "ko/observability/maxim", + "ko/observability/mlflow", + "ko/observability/neatlogs", + "ko/observability/openlit", + "ko/observability/opik", + "ko/observability/patronus-evaluation", + "ko/observability/portkey", + "ko/observability/weave" + ] + }, + { + "group": "학습", + "pages": [ + "ko/learn/overview", + "ko/learn/llm-selection-guide", + "ko/learn/conditional-tasks", + "ko/learn/coding-agents", + "ko/learn/create-custom-tools", + "ko/learn/custom-llm", + "ko/learn/custom-manager-agent", + "ko/learn/customizing-agents", + "ko/learn/dalle-image-generation", + "ko/learn/force-tool-output-as-result", + "ko/learn/hierarchical-process", + "ko/learn/human-input-on-execution", + "ko/learn/human-in-the-loop", + "ko/learn/human-feedback-in-flows", + "ko/learn/kickoff-async", + "ko/learn/kickoff-for-each", + "ko/learn/llm-connections", + "ko/learn/multimodal-agents", + "ko/learn/replay-tasks-from-latest-crew-kickoff", + "ko/learn/sequential-process", + "ko/learn/using-annotations", + "ko/learn/execution-hooks", + "ko/learn/llm-hooks", + "ko/learn/tool-hooks" + ] + }, + { + "group": "Telemetry", + "pages": [ + "ko/telemetry" + ] + } + ] + }, + { + "tab": "엔터프라이즈", + "icon": "briefcase", + "groups": [ + { + "group": "시작 안내", + "pages": [ + "ko/enterprise/introduction" + ] + }, + { + "group": "빌드", + "pages": [ + "ko/enterprise/features/automations", + "ko/enterprise/features/crew-studio", + "ko/enterprise/features/marketplace", + "ko/enterprise/features/agent-repositories", + "ko/enterprise/features/tools-and-integrations", + "ko/enterprise/features/pii-trace-redactions" + ] + }, + { + "group": "운영", + "pages": [ + "ko/enterprise/features/traces", + "ko/enterprise/features/webhook-streaming", + "ko/enterprise/features/hallucination-guardrail", + "ko/enterprise/features/flow-hitl-management" + ] + }, + { + "group": "관리", + "pages": [ + "ko/enterprise/features/rbac" + ] + }, + { + "group": "통합 문서", + "pages": [ + "ko/enterprise/integrations/asana", + "ko/enterprise/integrations/box", + "ko/enterprise/integrations/clickup", + "ko/enterprise/integrations/github", + "ko/enterprise/integrations/gmail", + "ko/enterprise/integrations/google_calendar", + "ko/enterprise/integrations/google_contacts", + "ko/enterprise/integrations/google_docs", + "ko/enterprise/integrations/google_drive", + "ko/enterprise/integrations/google_sheets", + "ko/enterprise/integrations/google_slides", + "ko/enterprise/integrations/hubspot", + "ko/enterprise/integrations/jira", + "ko/enterprise/integrations/linear", + "ko/enterprise/integrations/microsoft_excel", + "ko/enterprise/integrations/microsoft_onedrive", + "ko/enterprise/integrations/microsoft_outlook", + "ko/enterprise/integrations/microsoft_sharepoint", + "ko/enterprise/integrations/microsoft_teams", + "ko/enterprise/integrations/microsoft_word", + "ko/enterprise/integrations/notion", + "ko/enterprise/integrations/salesforce", + "ko/enterprise/integrations/shopify", + "ko/enterprise/integrations/slack", + "ko/enterprise/integrations/stripe", + "ko/enterprise/integrations/zendesk" + ] + }, + { + "group": "How-To Guides", + "pages": [ + "ko/enterprise/guides/build-crew", + "ko/enterprise/guides/prepare-for-deployment", + "ko/enterprise/guides/deploy-to-amp", + "ko/enterprise/guides/private-package-registry", + "ko/enterprise/guides/kickoff-crew", + "ko/enterprise/guides/update-crew", + "ko/enterprise/guides/enable-crew-studio", + "ko/enterprise/guides/capture_telemetry_logs", + "ko/enterprise/guides/azure-openai-setup", + "ko/enterprise/guides/tool-repository", + "ko/enterprise/guides/custom-mcp-server", + "ko/enterprise/guides/react-component-export", + "ko/enterprise/guides/team-management", + "ko/enterprise/guides/human-in-the-loop", + "ko/enterprise/guides/webhook-automation" + ] + }, + { + "group": "트리거", + "pages": [ + "ko/enterprise/guides/automation-triggers", + "ko/enterprise/guides/gmail-trigger", + "ko/enterprise/guides/google-calendar-trigger", + "ko/enterprise/guides/google-drive-trigger", + "ko/enterprise/guides/outlook-trigger", + "ko/enterprise/guides/onedrive-trigger", + "ko/enterprise/guides/microsoft-teams-trigger", + "ko/enterprise/guides/slack-trigger", + "ko/enterprise/guides/hubspot-trigger", + "ko/enterprise/guides/salesforce-trigger", + "ko/enterprise/guides/zapier-trigger" + ] + }, + { + "group": "학습 자원", + "pages": [ + "ko/enterprise/resources/frequently-asked-questions" + ] + } + ] + }, + { + "tab": "API 레퍼런스", + "icon": "magnifying-glass", + "groups": [ + { + "group": "시작 안내", + "pages": [ + "ko/api-reference/introduction", + "ko/api-reference/inputs", + "ko/api-reference/kickoff", + "ko/api-reference/resume", + "ko/api-reference/status" + ] + } + ] + }, + { + "tab": "예시", + "icon": "code", + "groups": [ + { + "group": "예시", + "pages": [ + "ko/examples/example", + "ko/examples/cookbooks" + ] + } + ] + }, + { + "tab": "변경 로그", + "icon": "clock", + "groups": [ + { + "group": "릴리스 노트", + "pages": [ + "ko/changelog" + ] + } + ] + } + ] + }, { "version": "v1.11.1", "tabs": [ @@ -7085,7 +8474,7 @@ }, "versions": [ { - "version": "v1.12.0", + "version": "v1.12.1", "default": true, "tabs": [ { @@ -7551,6 +8940,472 @@ } ] }, + { + "version": "v1.12.0", + "tabs": [ + { + "tab": "الرئيسية", + "icon": "house", + "groups": [ + { + "group": "مرحباً", + "pages": [ + "ar/index" + ] + } + ] + }, + { + "tab": "التقنية التوثيق", + "icon": "book-open", + "groups": [ + { + "group": "البدء", + "pages": [ + "ar/introduction", + "ar/installation", + "ar/quickstart" + ] + }, + { + "group": "الأدلّة", + "pages": [ + { + "group": "الاستراتيجية", + "icon": "compass", + "pages": [ + "ar/guides/concepts/evaluating-use-cases" + ] + }, + { + "group": "الوكلاء", + "icon": "user", + "pages": [ + "ar/guides/agents/crafting-effective-agents" + ] + }, + { + "group": "الطواقم", + "icon": "users", + "pages": [ + "ar/guides/crews/first-crew" + ] + }, + { + "group": "التدفقات", + "icon": "code-branch", + "pages": [ + "ar/guides/flows/first-flow", + "ar/guides/flows/mastering-flow-state" + ] + }, + { + "group": "الأدوات", + "icon": "wrench", + "pages": [ + "ar/guides/tools/publish-custom-tools" + ] + }, + { + "group": "أدوات البرمجة", + "icon": "terminal", + "pages": [ + "ar/guides/coding-tools/agents-md" + ] + }, + { + "group": "متقدّم", + "icon": "gear", + "pages": [ + "ar/guides/advanced/customizing-prompts", + "ar/guides/advanced/fingerprinting" + ] + }, + { + "group": "الترحيل", + "icon": "shuffle", + "pages": [ + "ar/guides/migration/migrating-from-langgraph" + ] + } + ] + }, + { + "group": "المفاهيم الأساسية", + "pages": [ + "ar/concepts/agents", + "ar/concepts/tasks", + "ar/concepts/crews", + "ar/concepts/flows", + "ar/concepts/production-architecture", + "ar/concepts/knowledge", + "ar/concepts/skills", + "ar/concepts/llms", + "ar/concepts/files", + "ar/concepts/processes", + "ar/concepts/collaboration", + "ar/concepts/training", + "ar/concepts/memory", + "ar/concepts/reasoning", + "ar/concepts/planning", + "ar/concepts/testing", + "ar/concepts/cli", + "ar/concepts/tools", + "ar/concepts/event-listener" + ] + }, + { + "group": "تكامل MCP", + "pages": [ + "ar/mcp/overview", + "ar/mcp/dsl-integration", + "ar/mcp/stdio", + "ar/mcp/sse", + "ar/mcp/streamable-http", + "ar/mcp/multiple-servers", + "ar/mcp/security" + ] + }, + { + "group": "الأدوات", + "pages": [ + "ar/tools/overview", + { + "group": "الملفات والمستندات", + "icon": "folder-open", + "pages": [ + "ar/tools/file-document/overview", + "ar/tools/file-document/filereadtool", + "ar/tools/file-document/filewritetool", + "ar/tools/file-document/pdfsearchtool", + "ar/tools/file-document/docxsearchtool", + "ar/tools/file-document/mdxsearchtool", + "ar/tools/file-document/xmlsearchtool", + "ar/tools/file-document/txtsearchtool", + "ar/tools/file-document/jsonsearchtool", + "ar/tools/file-document/csvsearchtool", + "ar/tools/file-document/directorysearchtool", + "ar/tools/file-document/directoryreadtool", + "ar/tools/file-document/ocrtool", + "ar/tools/file-document/pdf-text-writing-tool" + ] + }, + { + "group": "استخراج بيانات الويب", + "icon": "globe", + "pages": [ + "ar/tools/web-scraping/overview", + "ar/tools/web-scraping/scrapewebsitetool", + "ar/tools/web-scraping/scrapeelementfromwebsitetool", + "ar/tools/web-scraping/scrapflyscrapetool", + "ar/tools/web-scraping/seleniumscrapingtool", + "ar/tools/web-scraping/scrapegraphscrapetool", + "ar/tools/web-scraping/spidertool", + "ar/tools/web-scraping/browserbaseloadtool", + "ar/tools/web-scraping/hyperbrowserloadtool", + "ar/tools/web-scraping/stagehandtool", + "ar/tools/web-scraping/firecrawlcrawlwebsitetool", + "ar/tools/web-scraping/firecrawlscrapewebsitetool", + "ar/tools/web-scraping/oxylabsscraperstool", + "ar/tools/web-scraping/brightdata-tools" + ] + }, + { + "group": "البحث والاستكشاف", + "icon": "magnifying-glass", + "pages": [ + "ar/tools/search-research/overview", + "ar/tools/search-research/serperdevtool", + "ar/tools/search-research/bravesearchtool", + "ar/tools/search-research/exasearchtool", + "ar/tools/search-research/linkupsearchtool", + "ar/tools/search-research/githubsearchtool", + "ar/tools/search-research/websitesearchtool", + "ar/tools/search-research/codedocssearchtool", + "ar/tools/search-research/youtubechannelsearchtool", + "ar/tools/search-research/youtubevideosearchtool", + "ar/tools/search-research/tavilysearchtool", + "ar/tools/search-research/tavilyextractortool", + "ar/tools/search-research/arxivpapertool", + "ar/tools/search-research/serpapi-googlesearchtool", + "ar/tools/search-research/serpapi-googleshoppingtool", + "ar/tools/search-research/databricks-query-tool" + ] + }, + { + "group": "قواعد البيانات", + "icon": "database", + "pages": [ + "ar/tools/database-data/overview", + "ar/tools/database-data/mysqltool", + "ar/tools/database-data/pgsearchtool", + "ar/tools/database-data/snowflakesearchtool", + "ar/tools/database-data/nl2sqltool", + "ar/tools/database-data/qdrantvectorsearchtool", + "ar/tools/database-data/weaviatevectorsearchtool", + "ar/tools/database-data/mongodbvectorsearchtool", + "ar/tools/database-data/singlestoresearchtool" + ] + }, + { + "group": "الذكاء الاصطناعي والتعلّم الآلي", + "icon": "brain", + "pages": [ + "ar/tools/ai-ml/overview", + "ar/tools/ai-ml/dalletool", + "ar/tools/ai-ml/visiontool", + "ar/tools/ai-ml/aimindtool", + "ar/tools/ai-ml/llamaindextool", + "ar/tools/ai-ml/langchaintool", + "ar/tools/ai-ml/ragtool", + "ar/tools/ai-ml/codeinterpretertool" + ] + }, + { + "group": "التخزين السحابي", + "icon": "cloud", + "pages": [ + "ar/tools/cloud-storage/overview", + "ar/tools/cloud-storage/s3readertool", + "ar/tools/cloud-storage/s3writertool", + "ar/tools/cloud-storage/bedrockkbretriever" + ] + }, + { + "group": "Integrations", + "icon": "plug", + "pages": [ + "ar/tools/integration/overview", + "ar/tools/integration/bedrockinvokeagenttool", + "ar/tools/integration/crewaiautomationtool" + ] + }, + { + "group": "الأتمتة", + "icon": "bolt", + "pages": [ + "ar/tools/automation/overview", + "ar/tools/automation/apifyactorstool", + "ar/tools/automation/composiotool", + "ar/tools/automation/multiontool", + "ar/tools/automation/zapieractionstool" + ] + } + ] + }, + { + "group": "Observability", + "pages": [ + "ar/observability/tracing", + "ar/observability/overview", + "ar/observability/arize-phoenix", + "ar/observability/braintrust", + "ar/observability/datadog", + "ar/observability/galileo", + "ar/observability/langdb", + "ar/observability/langfuse", + "ar/observability/langtrace", + "ar/observability/maxim", + "ar/observability/mlflow", + "ar/observability/neatlogs", + "ar/observability/openlit", + "ar/observability/opik", + "ar/observability/patronus-evaluation", + "ar/observability/portkey", + "ar/observability/weave" + ] + }, + { + "group": "التعلّم", + "pages": [ + "ar/learn/overview", + "ar/learn/llm-selection-guide", + "ar/learn/conditional-tasks", + "ar/learn/coding-agents", + "ar/learn/create-custom-tools", + "ar/learn/custom-llm", + "ar/learn/custom-manager-agent", + "ar/learn/customizing-agents", + "ar/learn/dalle-image-generation", + "ar/learn/force-tool-output-as-result", + "ar/learn/hierarchical-process", + "ar/learn/human-input-on-execution", + "ar/learn/human-in-the-loop", + "ar/learn/human-feedback-in-flows", + "ar/learn/kickoff-async", + "ar/learn/kickoff-for-each", + "ar/learn/llm-connections", + "ar/learn/multimodal-agents", + "ar/learn/replay-tasks-from-latest-crew-kickoff", + "ar/learn/sequential-process", + "ar/learn/using-annotations", + "ar/learn/execution-hooks", + "ar/learn/llm-hooks", + "ar/learn/tool-hooks" + ] + }, + { + "group": "Telemetry", + "pages": [ + "ar/telemetry" + ] + } + ] + }, + { + "tab": "المؤسسات", + "icon": "briefcase", + "groups": [ + { + "group": "البدء", + "pages": [ + "ar/enterprise/introduction" + ] + }, + { + "group": "البناء", + "pages": [ + "ar/enterprise/features/automations", + "ar/enterprise/features/crew-studio", + "ar/enterprise/features/marketplace", + "ar/enterprise/features/agent-repositories", + "ar/enterprise/features/tools-and-integrations", + "ar/enterprise/features/pii-trace-redactions" + ] + }, + { + "group": "العمليات", + "pages": [ + "ar/enterprise/features/traces", + "ar/enterprise/features/webhook-streaming", + "ar/enterprise/features/hallucination-guardrail", + "ar/enterprise/features/flow-hitl-management" + ] + }, + { + "group": "الإدارة", + "pages": [ + "ar/enterprise/features/rbac" + ] + }, + { + "group": "التكاملات", + "pages": [ + "ar/enterprise/integrations/asana", + "ar/enterprise/integrations/box", + "ar/enterprise/integrations/clickup", + "ar/enterprise/integrations/github", + "ar/enterprise/integrations/gmail", + "ar/enterprise/integrations/google_calendar", + "ar/enterprise/integrations/google_contacts", + "ar/enterprise/integrations/google_docs", + "ar/enterprise/integrations/google_drive", + "ar/enterprise/integrations/google_sheets", + "ar/enterprise/integrations/google_slides", + "ar/enterprise/integrations/hubspot", + "ar/enterprise/integrations/jira", + "ar/enterprise/integrations/linear", + "ar/enterprise/integrations/microsoft_excel", + "ar/enterprise/integrations/microsoft_onedrive", + "ar/enterprise/integrations/microsoft_outlook", + "ar/enterprise/integrations/microsoft_sharepoint", + "ar/enterprise/integrations/microsoft_teams", + "ar/enterprise/integrations/microsoft_word", + "ar/enterprise/integrations/notion", + "ar/enterprise/integrations/salesforce", + "ar/enterprise/integrations/shopify", + "ar/enterprise/integrations/slack", + "ar/enterprise/integrations/stripe", + "ar/enterprise/integrations/zendesk" + ] + }, + { + "group": "How-To Guides", + "pages": [ + "ar/enterprise/guides/build-crew", + "ar/enterprise/guides/prepare-for-deployment", + "ar/enterprise/guides/deploy-to-amp", + "ar/enterprise/guides/private-package-registry", + "ar/enterprise/guides/kickoff-crew", + "ar/enterprise/guides/update-crew", + "ar/enterprise/guides/enable-crew-studio", + "ar/enterprise/guides/capture_telemetry_logs", + "ar/enterprise/guides/azure-openai-setup", + "ar/enterprise/guides/tool-repository", + "ar/enterprise/guides/custom-mcp-server", + "ar/enterprise/guides/react-component-export", + "ar/enterprise/guides/team-management", + "ar/enterprise/guides/human-in-the-loop", + "ar/enterprise/guides/webhook-automation" + ] + }, + { + "group": "المشغّلات", + "pages": [ + "ar/enterprise/guides/automation-triggers", + "ar/enterprise/guides/gmail-trigger", + "ar/enterprise/guides/google-calendar-trigger", + "ar/enterprise/guides/google-drive-trigger", + "ar/enterprise/guides/outlook-trigger", + "ar/enterprise/guides/onedrive-trigger", + "ar/enterprise/guides/microsoft-teams-trigger", + "ar/enterprise/guides/slack-trigger", + "ar/enterprise/guides/hubspot-trigger", + "ar/enterprise/guides/salesforce-trigger", + "ar/enterprise/guides/zapier-trigger" + ] + }, + { + "group": "موارد التعلّم", + "pages": [ + "ar/enterprise/resources/frequently-asked-questions" + ] + } + ] + }, + { + "tab": "API المرجع", + "icon": "magnifying-glass", + "groups": [ + { + "group": "البدء", + "pages": [ + "ar/api-reference/introduction", + "ar/api-reference/inputs", + "ar/api-reference/kickoff", + "ar/api-reference/resume", + "ar/api-reference/status" + ] + } + ] + }, + { + "tab": "أمثلة", + "icon": "code", + "groups": [ + { + "group": "أمثلة", + "pages": [ + "ar/examples/example", + "ar/examples/cookbooks" + ] + } + ] + }, + { + "tab": "التغييرات السجلات", + "icon": "clock", + "groups": [ + { + "group": "سجل التغييرات", + "pages": [ + "ar/changelog" + ] + } + ] + } + ] + }, { "version": "v1.11.1", "tabs": [ diff --git a/docs/en/changelog.mdx b/docs/en/changelog.mdx index 77a776de2..8d9b921fc 100644 --- a/docs/en/changelog.mdx +++ b/docs/en/changelog.mdx @@ -4,6 +4,46 @@ description: "Product updates, improvements, and bug fixes for CrewAI" icon: "clock" mode: "wide" --- + + ## v1.12.1 + + [View release on GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.12.1) + + ## What's Changed + + ### Features + - Add request_id to HumanFeedbackRequestedEvent + - Add Qdrant Edge storage backend for memory system + - Add docs-check command to analyze changes and generate docs with translations + - Add Arabic language support to changelog and release tooling + - Add modern standard Arabic translation of all documentation + - Add logout command in CLI + - Add agent skills + - Implement automatic root_scope for hierarchical memory isolation + - Implement native OpenAI-compatible providers (OpenRouter, DeepSeek, Ollama, vLLM, Cerebras, Dashscope) + + ### Bug Fixes + - Fix bad credentials for traces batch push (404) + - Resolve multiple bugs in HITL flow system + - Fix agent memory saving + - Resolve all strict mypy errors across crewai package + - Fix use of __router_paths__ for listener+router methods in FlowMeta + - Fix value error on no file support + - Correct litellm quarantine wording in docs + - Fix all mypy errors in crewai-files and add all packages to CI type checks + - Pin litellm upper bound to last tested version (1.82.6) + + ### Documentation + - Update changelog and version for v1.12.0 + - Add CONTRIBUTING.md + - Add guide for using CrewAI without LiteLLM + + ## Contributors + + @akaKuruma, @alex-clawd, @greysonlalonde, @iris-clawd, @joaomdmoura, @lorenzejay, @lucasgomide, @nicoferdi96 + + + ## v1.12.0 diff --git a/docs/ko/changelog.mdx b/docs/ko/changelog.mdx index 9fbb41352..c39cd4c1a 100644 --- a/docs/ko/changelog.mdx +++ b/docs/ko/changelog.mdx @@ -4,6 +4,46 @@ description: "CrewAI의 제품 업데이트, 개선 사항 및 버그 수정" icon: "clock" mode: "wide" --- + + ## v1.12.1 + + [GitHub 릴리스 보기](https://github.com/crewAIInc/crewAI/releases/tag/1.12.1) + + ## 변경 사항 + + ### 기능 + - HumanFeedbackRequestedEvent에 request_id 추가 + - 메모리 시스템을 위한 Qdrant Edge 저장소 백엔드 추가 + - 변경 사항을 분석하고 번역된 문서와 함께 문서를 생성하는 docs-check 명령어 추가 + - 변경 로그 및 릴리스 도구에 아랍어 지원 추가 + - 모든 문서에 대한 현대 표준 아랍어 번역 추가 + - CLI에 로그아웃 명령어 추가 + - 에이전트 기술 추가 + - 계층적 메모리 격리를 위한 자동 root_scope 구현 + - OpenAI 호환 네이티브 제공자 구현 (OpenRouter, DeepSeek, Ollama, vLLM, Cerebras, Dashscope) + + ### 버그 수정 + - 트레이스 배치 푸시에 대한 잘못된 자격 증명 수정 (404) + - HITL 흐름 시스템의 여러 버그 해결 + - 에이전트 메모리 저장 수정 + - crewai 패키지 전반에 걸쳐 모든 엄격한 mypy 오류 해결 + - FlowMeta의 listener+router 메서드에 대한 __router_paths__ 사용 수정 + - 파일 지원이 없는 경우 값 오류 수정 + - 문서에서 litellm 격리 단어 수정 + - crewai-files의 모든 mypy 오류 수정 및 모든 패키지를 CI 유형 검사에 추가 + - litellm의 상한을 마지막 테스트된 버전 (1.82.6)으로 고정 + + ### 문서 + - v1.12.0에 대한 변경 로그 및 버전 업데이트 + - CONTRIBUTING.md 추가 + - LiteLLM 없이 CrewAI를 사용하는 가이드 추가 + + ## 기여자 + + @akaKuruma, @alex-clawd, @greysonlalonde, @iris-clawd, @joaomdmoura, @lorenzejay, @lucasgomide, @nicoferdi96 + + + ## v1.12.0 diff --git a/docs/pt-BR/changelog.mdx b/docs/pt-BR/changelog.mdx index 18a27745c..a21d2f1d8 100644 --- a/docs/pt-BR/changelog.mdx +++ b/docs/pt-BR/changelog.mdx @@ -4,6 +4,46 @@ description: "Atualizações de produto, melhorias e correções do CrewAI" icon: "clock" mode: "wide" --- + + ## v1.12.1 + + [Ver release no GitHub](https://github.com/crewAIInc/crewAI/releases/tag/1.12.1) + + ## O que Mudou + + ### Recursos + - Adicionar request_id ao HumanFeedbackRequestedEvent + - Adicionar backend de armazenamento Qdrant Edge para sistema de memória + - Adicionar comando docs-check para analisar mudanças e gerar documentação com traduções + - Adicionar suporte ao idioma árabe para changelog e ferramentas de lançamento + - Adicionar tradução em árabe padrão moderno de toda a documentação + - Adicionar comando de logout na CLI + - Adicionar habilidades de agente + - Implementar root_scope automático para isolamento hierárquico de memória + - Implementar provedores nativos compatíveis com OpenAI (OpenRouter, DeepSeek, Ollama, vLLM, Cerebras, Dashscope) + + ### Correções de Bugs + - Corrigir credenciais incorretas para envio em lote de traces (404) + - Resolver múltiplos bugs no sistema de fluxo HITL + - Corrigir salvamento de memória do agente + - Resolver todos os erros estritos do mypy no pacote crewai + - Corrigir uso de __router_paths__ para métodos listener+router em FlowMeta + - Corrigir erro de valor em caso de suporte a nenhum arquivo + - Corrigir redação da quarentena do litellm na documentação + - Corrigir todos os erros do mypy em crewai-files e adicionar todos os pacotes às verificações de tipo do CI + - Fixar limite superior do litellm na última versão testada (1.82.6) + + ### Documentação + - Atualizar changelog e versão para v1.12.0 + - Adicionar CONTRIBUTING.md + - Adicionar guia para usar CrewAI sem LiteLLM + + ## Contribuidores + + @akaKuruma, @alex-clawd, @greysonlalonde, @iris-clawd, @joaomdmoura, @lorenzejay, @lucasgomide, @nicoferdi96 + + + ## v1.12.0 From a91cd1a7d783639a26668e70c4165fdb59f8446e Mon Sep 17 00:00:00 2001 From: Rip&Tear <84775494+theCyberTech@users.noreply.github.com> Date: Thu, 26 Mar 2026 10:50:21 +0800 Subject: [PATCH 24/25] Revise security policy and reporting instructions (#5096) * Revise security policy and reporting instructions Updated the security reporting process and contact details. * Update .github/security.md --------- --- .github/security.md | 50 ++++++--------------------------------------- 1 file changed, 6 insertions(+), 44 deletions(-) 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 From bd03f6cf648390bd4af63f5fd69e1178205c3e79 Mon Sep 17 00:00:00 2001 From: Greyson LaLonde Date: Thu, 26 Mar 2026 12:22:37 +0800 Subject: [PATCH 25/25] feat: add enterprise release phase to devtools release --- lib/devtools/README.md | 16 +- lib/devtools/src/crewai_devtools/cli.py | 413 ++++++++++++++++++++++-- 2 files changed, 395 insertions(+), 34 deletions(-) diff --git a/lib/devtools/README.md b/lib/devtools/README.md index 699c05593..e70721b52 100644 --- a/lib/devtools/README.md +++ b/lib/devtools/README.md @@ -8,18 +8,22 @@ Installed automatically via the workspace (`uv sync`). Requires: - [GitHub CLI](https://cli.github.com/) (`gh`) — authenticated - `OPENAI_API_KEY` env var — for release note generation and translation +- `ENTERPRISE_REPO` env var — GitHub repo for enterprise releases +- `ENTERPRISE_VERSION_DIRS` env var — comma-separated directories to bump in the enterprise repo +- `ENTERPRISE_CREWAI_DEP_PATH` env var — path to the pyproject.toml with the `crewai[tools]` pin in the enterprise repo ## Commands ### `devtools release ` -Full end-to-end release. Bumps versions, creates PRs, tags, and publishes a GitHub release. +Full end-to-end release. Bumps versions, creates PRs, tags, publishes a GitHub release, and releases the enterprise repo. ``` devtools release 1.10.3 -devtools release 1.10.3a1 # pre-release -devtools release 1.10.3 --no-edit # skip editing release notes -devtools release 1.10.3 --dry-run # preview without changes +devtools release 1.10.3a1 # pre-release +devtools release 1.10.3 --no-edit # skip editing release notes +devtools release 1.10.3 --dry-run # preview without changes +devtools release 1.10.3 --skip-enterprise # skip enterprise release phase ``` **Flow:** @@ -31,6 +35,10 @@ devtools release 1.10.3 --dry-run # preview without changes 5. Updates changelogs (en, pt-BR, ko) and docs version switcher 6. Creates docs PR against main, polls until merged 7. Tags main and creates GitHub release +8. Triggers PyPI publish workflow +9. Clones enterprise repo, bumps versions and `crewai[tools]` dep, runs `uv sync` +10. Creates enterprise bump PR, polls until merged +11. Tags and creates GitHub release on enterprise repo ### `devtools bump ` diff --git a/lib/devtools/src/crewai_devtools/cli.py b/lib/devtools/src/crewai_devtools/cli.py index ca95a0e9c..6342ba9ec 100644 --- a/lib/devtools/src/crewai_devtools/cli.py +++ b/lib/devtools/src/crewai_devtools/cli.py @@ -2,10 +2,13 @@ import os from pathlib import Path +import re import subprocess import sys +import tempfile import time from typing import Final, Literal +from urllib.request import urlopen import click from dotenv import load_dotenv @@ -153,12 +156,24 @@ def update_version_in_file(file_path: Path, new_version: str) -> bool: return False -def update_pyproject_dependencies(file_path: Path, new_version: str) -> bool: +_DEFAULT_WORKSPACE_PACKAGES: Final[list[str]] = [ + "crewai", + "crewai-tools", + "crewai-devtools", +] + + +def update_pyproject_dependencies( + file_path: Path, + new_version: str, + extra_packages: list[str] | None = None, +) -> bool: """Update workspace dependency versions in pyproject.toml. Args: file_path: Path to pyproject.toml file. new_version: New version string. + extra_packages: Additional package names to update beyond the defaults. Returns: True if any dependencies were updated, False otherwise. @@ -170,7 +185,7 @@ def update_pyproject_dependencies(file_path: Path, new_version: str) -> bool: lines = content.splitlines() updated = False - workspace_packages = ["crewai", "crewai-tools", "crewai-devtools"] + workspace_packages = _DEFAULT_WORKSPACE_PACKAGES + (extra_packages or []) for i, line in enumerate(lines): for pkg in workspace_packages: @@ -431,12 +446,29 @@ def update_changelog( return True -def update_template_dependencies(templates_dir: Path, new_version: str) -> list[Path]: - """Update crewai dependency versions in CLI template pyproject.toml files. +def _pin_crewai_deps(content: str, version: str) -> str: + """Replace crewai dependency version pins in a pyproject.toml string. Handles both pinned (==) and minimum (>=) version specifiers, as well as extras like [tools]. + Args: + content: File content to transform. + version: New version string. + + Returns: + Transformed content. + """ + return re.sub( + r'"crewai(\[tools\])?(==|>=)[^"]*"', + lambda m: f'"crewai{(m.group(1) or "")!s}=={version}"', + content, + ) + + +def update_template_dependencies(templates_dir: Path, new_version: str) -> list[Path]: + """Update crewai dependency versions in CLI template pyproject.toml files. + Args: templates_dir: Path to the CLI templates directory. new_version: New version string. @@ -444,16 +476,10 @@ def update_template_dependencies(templates_dir: Path, new_version: str) -> list[ Returns: List of paths that were updated. """ - import re - updated = [] for pyproject in templates_dir.rglob("pyproject.toml"): content = pyproject.read_text() - new_content = re.sub( - r'"crewai(\[tools\])?(==|>=)[^"]*"', - lambda m: f'"crewai{(m.group(1) or "")!s}=={new_version}"', - content, - ) + new_content = _pin_crewai_deps(content, new_version) if new_content != content: pyproject.write_text(new_content) updated.append(pyproject) @@ -607,24 +633,26 @@ def get_github_contributors(commit_range: str) -> list[str]: # --------------------------------------------------------------------------- -def _poll_pr_until_merged(branch_name: str, label: str) -> None: - """Poll a GitHub PR until it is merged. Exit if closed without merging.""" +def _poll_pr_until_merged( + branch_name: str, label: str, repo: str | None = None +) -> None: + """Poll a GitHub PR until it is merged. Exit if closed without merging. + + Args: + branch_name: Branch name to look up the PR. + label: Human-readable label for status messages. + repo: Optional GitHub repo (owner/name) for cross-repo PRs. + """ console.print(f"[cyan]Waiting for {label} to be merged...[/cyan]") + cmd = ["gh", "pr", "view", branch_name] + if repo: + cmd.extend(["--repo", repo]) + cmd.extend(["--json", "state", "--jq", ".state"]) + while True: time.sleep(10) try: - state = run_command( - [ - "gh", - "pr", - "view", - branch_name, - "--json", - "state", - "--jq", - ".state", - ] - ) + state = run_command(cmd) except subprocess.CalledProcessError: state = "" @@ -984,8 +1012,252 @@ def _create_tag_and_release( console.print(f"[green]✓[/green] Created GitHub {release_type} for {tag_name}") -def _trigger_pypi_publish(tag_name: str) -> None: - """Trigger the PyPI publish GitHub Actions workflow.""" +_ENTERPRISE_REPO: Final[str | None] = os.getenv("ENTERPRISE_REPO") +_ENTERPRISE_VERSION_DIRS: Final[tuple[str, ...]] = tuple( + d.strip() for d in os.getenv("ENTERPRISE_VERSION_DIRS", "").split(",") if d.strip() +) +_ENTERPRISE_CREWAI_DEP_PATH: Final[str | None] = os.getenv("ENTERPRISE_CREWAI_DEP_PATH") +_ENTERPRISE_EXTRA_PACKAGES: Final[tuple[str, ...]] = tuple( + p.strip() + for p in os.getenv("ENTERPRISE_EXTRA_PACKAGES", "").split(",") + if p.strip() +) + + +def _update_enterprise_crewai_dep(pyproject_path: Path, version: str) -> bool: + """Update the crewai[tools] pin in an enterprise pyproject.toml. + + Args: + pyproject_path: Path to the pyproject.toml file. + version: New crewai version string. + + Returns: + True if the file was modified. + """ + if not pyproject_path.exists(): + return False + + content = pyproject_path.read_text() + new_content = _pin_crewai_deps(content, version) + if new_content != content: + pyproject_path.write_text(new_content) + return True + return False + + +_PYPI_POLL_INTERVAL: Final[int] = 15 +_PYPI_POLL_TIMEOUT: Final[int] = 600 + + +def _wait_for_pypi(package: str, version: str) -> None: + """Poll PyPI until a specific package version is available. + + Args: + package: PyPI package name. + version: Version string to wait for. + """ + url = f"https://pypi.org/pypi/{package}/{version}/json" + deadline = time.monotonic() + _PYPI_POLL_TIMEOUT + + console.print(f"[cyan]Waiting for {package}=={version} to appear on PyPI...[/cyan]") + while time.monotonic() < deadline: + try: + with urlopen(url) as resp: # noqa: S310 + if resp.status == 200: + console.print( + f"[green]✓[/green] {package}=={version} is available on PyPI" + ) + return + except Exception: # noqa: S110 + pass + time.sleep(_PYPI_POLL_INTERVAL) + + console.print( + f"[red]Error:[/red] Timed out waiting for {package}=={version} on PyPI" + ) + sys.exit(1) + + +def _release_enterprise(version: str, is_prerelease: bool, dry_run: bool) -> None: + """Clone the enterprise repo, bump versions, and create a release PR. + + Expects ENTERPRISE_REPO, ENTERPRISE_VERSION_DIRS, and + ENTERPRISE_CREWAI_DEP_PATH to be validated before calling. + + Args: + version: New version string. + is_prerelease: Whether this is a pre-release version. + dry_run: Show what would be done without making changes. + """ + if ( + not _ENTERPRISE_REPO + or not _ENTERPRISE_VERSION_DIRS + or not _ENTERPRISE_CREWAI_DEP_PATH + ): + console.print("[red]Error:[/red] Enterprise env vars not configured") + sys.exit(1) + + enterprise_repo: str = _ENTERPRISE_REPO + enterprise_dep_path: str = _ENTERPRISE_CREWAI_DEP_PATH + + console.print( + f"\n[bold cyan]Phase 3: Releasing {enterprise_repo} {version}[/bold cyan]" + ) + + if dry_run: + console.print(f"[dim][DRY RUN][/dim] Would clone {enterprise_repo}") + for d in _ENTERPRISE_VERSION_DIRS: + console.print(f"[dim][DRY RUN][/dim] Would update versions in {d}") + console.print( + f"[dim][DRY RUN][/dim] Would update crewai[tools] dep in " + f"{enterprise_dep_path}" + ) + console.print( + "[dim][DRY RUN][/dim] Would create bump PR, wait for merge, " + "then tag and release" + ) + return + + with tempfile.TemporaryDirectory() as tmp: + repo_dir = Path(tmp) / enterprise_repo.split("/")[-1] + console.print(f"Cloning {enterprise_repo}...") + run_command(["gh", "repo", "clone", enterprise_repo, str(repo_dir)]) + console.print(f"[green]✓[/green] Cloned {enterprise_repo}") + + # --- bump versions --- + for rel_dir in _ENTERPRISE_VERSION_DIRS: + pkg_dir = repo_dir / rel_dir + if not pkg_dir.exists(): + console.print( + f"[yellow]Warning:[/yellow] {rel_dir} not found, skipping" + ) + continue + + for vfile in find_version_files(pkg_dir): + if update_version_in_file(vfile, version): + console.print( + f"[green]✓[/green] Updated: {vfile.relative_to(repo_dir)}" + ) + + pyproject = pkg_dir / "pyproject.toml" + if pyproject.exists(): + if update_pyproject_dependencies( + pyproject, version, extra_packages=list(_ENTERPRISE_EXTRA_PACKAGES) + ): + console.print( + f"[green]✓[/green] Updated deps in: " + f"{pyproject.relative_to(repo_dir)}" + ) + + # --- update crewai[tools] pin --- + enterprise_pyproject = repo_dir / enterprise_dep_path + if _update_enterprise_crewai_dep(enterprise_pyproject, version): + console.print( + f"[green]✓[/green] Updated crewai[tools] dep in {enterprise_dep_path}" + ) + + _wait_for_pypi("crewai", version) + + console.print("\nSyncing workspace...") + run_command(["uv", "sync"], cwd=repo_dir) + console.print("[green]✓[/green] Workspace synced") + + # --- branch, commit, push, PR --- + branch_name = f"feat/bump-version-{version}" + run_command(["git", "checkout", "-b", branch_name], cwd=repo_dir) + run_command(["git", "add", "."], cwd=repo_dir) + run_command( + ["git", "commit", "-m", f"feat: bump versions to {version}"], + cwd=repo_dir, + ) + console.print("[green]✓[/green] Changes committed") + + run_command(["git", "push", "-u", "origin", branch_name], cwd=repo_dir) + console.print("[green]✓[/green] Branch pushed") + + run_command( + [ + "gh", + "pr", + "create", + "--repo", + enterprise_repo, + "--base", + "main", + "--title", + f"feat: bump versions to {version}", + "--body", + "", + ], + cwd=repo_dir, + ) + console.print("[green]✓[/green] Enterprise bump PR created") + + _poll_pr_until_merged(branch_name, "enterprise bump PR", repo=enterprise_repo) + + # --- tag and release --- + run_command(["git", "checkout", "main"], cwd=repo_dir) + run_command(["git", "pull"], cwd=repo_dir) + + tag_name = version + run_command( + ["git", "tag", "-a", tag_name, "-m", f"Release {version}"], + cwd=repo_dir, + ) + run_command(["git", "push", "origin", tag_name], cwd=repo_dir) + console.print(f"[green]✓[/green] Pushed tag {tag_name}") + + gh_cmd = [ + "gh", + "release", + "create", + tag_name, + "--repo", + enterprise_repo, + "--title", + tag_name, + "--notes", + f"Release {version}", + ] + if is_prerelease: + gh_cmd.append("--prerelease") + + run_command(gh_cmd) + release_type = "prerelease" if is_prerelease else "release" + console.print( + f"[green]✓[/green] Created GitHub {release_type} for " + f"{enterprise_repo} {tag_name}" + ) + + +def _trigger_pypi_publish(tag_name: str, wait: bool = False) -> None: + """Trigger the PyPI publish GitHub Actions workflow. + + Args: + tag_name: The release tag to publish. + wait: Block until the workflow run completes. + """ + # Capture the latest run ID before triggering so we can detect the new one + prev_run_id = "" + if wait: + try: + prev_run_id = run_command( + [ + "gh", + "run", + "list", + "--workflow=publish.yml", + "--limit=1", + "--json=databaseId", + "--jq=.[0].databaseId", + ] + ) + except subprocess.CalledProcessError: + console.print( + "[yellow]Note:[/yellow] Could not determine previous workflow run; " + "continuing without previous run ID" + ) + with console.status("[cyan]Triggering PyPI publish workflow..."): try: run_command( @@ -1003,6 +1275,42 @@ def _trigger_pypi_publish(tag_name: str) -> None: sys.exit(1) console.print("[green]✓[/green] Triggered PyPI publish workflow") + if wait: + console.print("[cyan]Waiting for PyPI publish workflow to complete...[/cyan]") + run_id = "" + deadline = time.monotonic() + 120 + while time.monotonic() < deadline: + time.sleep(5) + try: + run_id = run_command( + [ + "gh", + "run", + "list", + "--workflow=publish.yml", + "--limit=1", + "--json=databaseId", + "--jq=.[0].databaseId", + ] + ) + except subprocess.CalledProcessError: + continue + if run_id and run_id != prev_run_id: + break + + if not run_id or run_id == prev_run_id: + console.print( + "[red]Error:[/red] Could not find the PyPI publish workflow run" + ) + sys.exit(1) + + try: + run_command(["gh", "run", "watch", run_id, "--exit-status"]) + except subprocess.CalledProcessError as e: + console.print(f"[red]✗[/red] PyPI publish workflow failed: {e}") + sys.exit(1) + console.print("[green]✓[/green] PyPI publish workflow completed") + # --------------------------------------------------------------------------- # CLI commands @@ -1032,6 +1340,15 @@ def bump(version: str, dry_run: bool, no_push: bool, no_commit: bool) -> None: no_push: Don't push changes to remote. no_commit: Don't commit changes (just update files). """ + console.print( + f"\n[yellow]Note:[/yellow] [bold]devtools bump[/bold] only bumps versions " + f"in this repo. It will not tag, publish to PyPI, or release enterprise.\n" + f"If you want a full end-to-end release, run " + f"[bold]devtools release {version}[/bold] instead." + ) + if not Confirm.ask("Continue with bump only?", default=True): + sys.exit(0) + try: check_gh_installed() @@ -1136,6 +1453,16 @@ def tag(dry_run: bool, no_edit: bool) -> None: dry_run: Show what would be done without making changes. no_edit: Skip editing release notes. """ + console.print( + "\n[yellow]Note:[/yellow] [bold]devtools tag[/bold] only tags and creates " + "a GitHub release for this repo. It will not bump versions, publish to " + "PyPI, or release enterprise.\n" + "If you want a full end-to-end release, run " + "[bold]devtools release [/bold] instead." + ) + if not Confirm.ask("Continue with tag only?", default=True): + sys.exit(0) + try: cwd = Path.cwd() lib_dir = cwd / "lib" @@ -1226,21 +1553,44 @@ def tag(dry_run: bool, no_edit: bool) -> None: "--dry-run", is_flag=True, help="Show what would be done without making changes" ) @click.option("--no-edit", is_flag=True, help="Skip editing release notes") -def release(version: str, dry_run: bool, no_edit: bool) -> None: +@click.option( + "--skip-enterprise", + is_flag=True, + help="Skip the enterprise release phase", +) +def release(version: str, dry_run: bool, no_edit: bool, skip_enterprise: bool) -> None: """Full release: bump versions, tag, and publish a GitHub release. Combines bump and tag into a single workflow. Creates a version bump PR, waits for it to be merged, then generates release notes, updates docs, - creates the tag, and publishes a GitHub release. + creates the tag, and publishes a GitHub release. Then bumps versions and + releases the enterprise repo. Args: version: New version to set (e.g., 1.0.0, 1.0.0a1). dry_run: Show what would be done without making changes. no_edit: Skip editing release notes. + skip_enterprise: Skip the enterprise release phase. """ try: check_gh_installed() + if not skip_enterprise: + missing: list[str] = [] + if not _ENTERPRISE_REPO: + missing.append("ENTERPRISE_REPO") + if not _ENTERPRISE_VERSION_DIRS: + missing.append("ENTERPRISE_VERSION_DIRS") + if not _ENTERPRISE_CREWAI_DEP_PATH: + missing.append("ENTERPRISE_CREWAI_DEP_PATH") + if missing: + console.print( + f"[red]Error:[/red] Missing required environment variable(s): " + f"{', '.join(missing)}\n" + f"Set them or pass --skip-enterprise to skip the enterprise release." + ) + sys.exit(1) + cwd = Path.cwd() lib_dir = cwd / "lib" @@ -1337,7 +1687,10 @@ def release(version: str, dry_run: bool, no_edit: bool) -> None: if not dry_run: _create_tag_and_release(tag_name, release_notes, is_prerelease) - _trigger_pypi_publish(tag_name) + _trigger_pypi_publish(tag_name, wait=not skip_enterprise) + + if not skip_enterprise: + _release_enterprise(version, is_prerelease, dry_run) console.print(f"\n[green]✓[/green] Release [bold]{version}[/bold] complete!")