diff --git a/docs/ar/concepts/agent-capabilities.mdx b/docs/ar/concepts/agent-capabilities.mdx new file mode 100644 index 000000000..5d29ec95e --- /dev/null +++ b/docs/ar/concepts/agent-capabilities.mdx @@ -0,0 +1,147 @@ +--- +title: "قدرات الوكيل" +description: "فهم الطرق الخمس لتوسيع وكلاء CrewAI: الأدوات، MCP، التطبيقات، المهارات، والمعرفة." +icon: puzzle-piece +mode: "wide" +--- + +## نظرة عامة + +يمكن توسيع وكلاء CrewAI بـ **خمسة أنواع مميزة من القدرات**، كل منها يخدم غرضًا مختلفًا. فهم متى تستخدم كل نوع — وكيف يعملون معًا — هو المفتاح لبناء وكلاء فعّالين. + + + + **دوال قابلة للاستدعاء** — تمنح الوكلاء القدرة على اتخاذ إجراءات. البحث على الويب، عمليات الملفات، استدعاءات API، تنفيذ الكود. + + + **خوادم أدوات عن بُعد** — تربط الوكلاء بخوادم أدوات خارجية عبر Model Context Protocol. نفس تأثير الأدوات، لكن مستضافة خارجيًا. + + + **تكاملات المنصة** — تربط الوكلاء بتطبيقات SaaS (Gmail، Slack، Jira، Salesforce) عبر طبقة OAuth المُدارة من CrewAI. + + + **خبرة المجال** — تحقن التعليمات والإرشادات والمواد المرجعية في إرشادات الوكلاء. المهارات تخبر الوكلاء *كيف يفكرون*. + + + **حقائق مُسترجعة** — توفر للوكلاء بيانات من المستندات والملفات وعناوين URL عبر البحث الدلالي (RAG). المعرفة تعطي الوكلاء *ما يحتاجون معرفته*. + + + +--- + +## التمييز الأساسي + +أهم شيء يجب فهمه: **هذه القدرات تنقسم إلى فئتين**. + +### قدرات الإجراء (الأدوات، MCP، التطبيقات) + +تمنح الوكلاء القدرة على **فعل أشياء** — استدعاء APIs، قراءة الملفات، البحث على الويب، إرسال رسائل البريد الإلكتروني. عند التنفيذ، تتحول الأنواع الثلاثة إلى نفس التنسيق الداخلي (مثيلات `BaseTool`) وتظهر في قائمة أدوات موحدة يمكن للوكيل استدعاؤها. + +```python +from crewai import Agent +from crewai_tools import SerperDevTool, FileReadTool + +agent = Agent( + role="Researcher", + goal="Find and compile market data", + backstory="Expert market analyst", + tools=[SerperDevTool(), FileReadTool()], # أدوات محلية + mcps=["https://mcp.example.com/sse"], # أدوات خادم MCP عن بُعد + apps=["gmail", "google_sheets"], # تكاملات المنصة +) +``` + +### قدرات السياق (المهارات، المعرفة) + +تُعدّل **إرشادات** الوكيل — بحقن الخبرة أو التعليمات أو البيانات المُسترجعة قبل أن يبدأ الوكيل في التفكير. لا تمنح الوكلاء إجراءات جديدة؛ بل تُشكّل كيف يفكر الوكلاء وما هي المعلومات التي يمكنهم الوصول إليها. + +```python +from crewai import Agent + +agent = Agent( + role="Security Auditor", + goal="Audit cloud infrastructure for vulnerabilities", + backstory="Expert in cloud security with 10 years of experience", + skills=["./skills/security-audit"], # تعليمات المجال + knowledge_sources=[pdf_source, url_source], # حقائق مُسترجعة +) +``` + +--- + +## متى تستخدم ماذا + +| تحتاج إلى... | استخدم | مثال | +| :------------------------------------------------------- | :---------------- | :--------------------------------------- | +| الوكيل يبحث على الويب | **الأدوات** | `tools=[SerperDevTool()]` | +| الوكيل يستدعي API عن بُعد عبر MCP | **MCP** | `mcps=["https://api.example.com/sse"]` | +| الوكيل يرسل بريد إلكتروني عبر Gmail | **التطبيقات** | `apps=["gmail"]` | +| الوكيل يتبع إجراءات محددة | **المهارات** | `skills=["./skills/code-review"]` | +| الوكيل يرجع لمستندات الشركة | **المعرفة** | `knowledge_sources=[pdf_source]` | +| الوكيل يبحث على الويب ويتبع إرشادات المراجعة | **الأدوات + المهارات** | استخدم كليهما معًا | + +--- + +## دمج القدرات + +في الممارسة العملية، غالبًا ما يستخدم الوكلاء **أنواعًا متعددة من القدرات معًا**. إليك مثال واقعي: + +```python +from crewai import Agent +from crewai_tools import SerperDevTool, FileReadTool, CodeInterpreterTool + +# وكيل بحث مجهز بالكامل +researcher = Agent( + role="Senior Research Analyst", + goal="Produce comprehensive market analysis reports", + backstory="Expert analyst with deep industry knowledge", + + # الإجراء: ما يمكن للوكيل فعله + tools=[ + SerperDevTool(), # البحث على الويب + FileReadTool(), # قراءة الملفات المحلية + CodeInterpreterTool(), # تشغيل كود Python للتحليل + ], + mcps=["https://data-api.example.com/sse"], # الوصول لـ API بيانات عن بُعد + apps=["google_sheets"], # الكتابة في Google Sheets + + # السياق: ما يعرفه الوكيل + skills=["./skills/research-methodology"], # كيفية إجراء البحث + knowledge_sources=[company_docs], # بيانات خاصة بالشركة +) +``` + +--- + +## جدول المقارنة + +| الميزة | الأدوات | MCP | التطبيقات | المهارات | المعرفة | +| :--- | :---: | :---: | :---: | :---: | :---: | +| **يمنح الوكيل إجراءات** | ✅ | ✅ | ✅ | ❌ | ❌ | +| **يُعدّل الإرشادات** | ❌ | ❌ | ❌ | ✅ | ✅ | +| **يتطلب كود** | نعم | إعداد فقط | إعداد فقط | Markdown فقط | إعداد فقط | +| **يعمل محليًا** | نعم | يعتمد | لا (AMP API) | غير متاح | نعم | +| **يحتاج مفاتيح API** | لكل أداة | لكل خادم | OAuth عبر AMP | لا | المُضمّن فقط | +| **يُعيَّن على Agent** | `tools=[]` | `mcps=[]` | `apps=[]` | `skills=[]` | `knowledge_sources=[]` | +| **يُعيَّن على Crew** | ❌ | ❌ | ❌ | `skills=[]` | `knowledge_sources=[]` | + +--- + +## تعمّق أكثر + +هل أنت مستعد لمعرفة المزيد عن كل نوع من أنواع القدرات؟ + + + + إنشاء أدوات مخصصة، استخدام كتالوج OSS مع أكثر من 75 خيارًا، تكوين التخزين المؤقت والتنفيذ غير المتزامن. + + + الاتصال بخوادم MCP عبر stdio أو SSE أو HTTP. تصفية الأدوات، تكوين المصادقة. + + + بناء حزم المهارات مع SKILL.md، حقن خبرة المجال، استخدام الكشف التدريجي. + + + إضافة المعرفة من ملفات PDF وCSV وعناوين URL والمزيد. تكوين المُضمّنات والاسترجاع. + + diff --git a/docs/ar/concepts/skills.mdx b/docs/ar/concepts/skills.mdx index ea883edd1..89f29a90a 100644 --- a/docs/ar/concepts/skills.mdx +++ b/docs/ar/concepts/skills.mdx @@ -1,15 +1,217 @@ --- title: المهارات -description: حزم المهارات المبنية على نظام الملفات التي تحقن السياق في إرشادات الوكيل. +description: حزم المهارات المبنية على نظام الملفات التي تحقن خبرة المجال والتعليمات في إرشادات الوكلاء. icon: bolt mode: "wide" --- ## نظرة عامة -المهارات هي مجلدات مستقلة توفر للوكلاء تعليمات ومراجع وموارد خاصة بالمجال. تُعرّف كل مهارة بملف `SKILL.md` يحتوي على بيانات وصفية YAML ومحتوى Markdown. +المهارات هي مجلدات مستقلة توفر للوكلاء **تعليمات وإرشادات ومواد مرجعية خاصة بالمجال**. تُعرّف كل مهارة بملف `SKILL.md` يحتوي على بيانات وصفية YAML ومحتوى Markdown. -تستخدم المهارات **الكشف التدريجي** — يتم تحميل البيانات الوصفية أولاً، ثم التعليمات الكاملة فقط عند التفعيل، وكتالوجات الموارد فقط عند الحاجة. +عند التفعيل، يتم حقن تعليمات المهارة مباشرة في إرشادات مهمة الوكيل — مما يمنح الوكيل خبرة دون الحاجة لأي تغييرات في الكود. + + +**المهارات ليست أدوات.** هذه هي نقطة الارتباك الأكثر شيوعًا. + +- **المهارات** تحقن *تعليمات وسياق* في إرشادات الوكيل. تخبر الوكيل *كيف يفكر* في مشكلة ما. +- **الأدوات** تمنح الوكيل *دوال قابلة للاستدعاء* لاتخاذ إجراءات (البحث، قراءة الملفات، استدعاء APIs). + +غالبًا ما تحتاج **كليهما**: مهارات للخبرة، وأدوات للإجراء. يتم تكوينهما بشكل مستقل ويُكمّلان بعضهما. + + +--- + +## البداية السريعة + +### 1. إنشاء مجلد المهارة + +``` +skills/ +└── code-review/ + ├── SKILL.md # مطلوب — التعليمات + ├── references/ # اختياري — مستندات مرجعية + │ └── style-guide.md + └── scripts/ # اختياري — سكربتات قابلة للتنفيذ +``` + +### 2. كتابة SKILL.md الخاص بك + +```markdown +--- +name: code-review +description: Guidelines for conducting thorough code reviews with focus on security and performance. +metadata: + author: your-team + version: "1.0" +--- + +## إرشادات مراجعة الكود + +عند مراجعة الكود، اتبع قائمة التحقق هذه: + +1. **الأمان**: تحقق من ثغرات الحقن وتجاوز المصادقة وكشف البيانات +2. **الأداء**: ابحث عن استعلامات N+1 والتخصيصات غير الضرورية والاستدعاءات المحظورة +3. **القابلية للقراءة**: تأكد من وضوح التسمية والتعليقات المناسبة والأسلوب المتسق +4. **الاختبارات**: تحقق من تغطية اختبار كافية للوظائف الجديدة + +### مستويات الخطورة +- **حرج**: ثغرات أمنية، مخاطر فقدان البيانات → حظر الدمج +- **رئيسي**: مشاكل أداء، أخطاء منطقية → طلب تغييرات +- **ثانوي**: مسائل أسلوبية، اقتراحات تسمية → الموافقة مع تعليقات +``` + +### 3. ربطها بوكيل + +```python +from crewai import Agent +from crewai_tools import GithubSearchTool, FileReadTool + +reviewer = Agent( + role="Senior Code Reviewer", + goal="Review pull requests for quality and security issues", + backstory="Staff engineer with expertise in secure coding practices.", + skills=["./skills"], # يحقن إرشادات المراجعة + tools=[GithubSearchTool(), FileReadTool()], # يسمح للوكيل بقراءة الكود +) +``` + +الوكيل الآن لديه **خبرة** (من المهارة) و**قدرات** (من الأدوات) معًا. + +--- + +## المهارات + الأدوات: العمل معًا + +إليك أنماط شائعة توضح كيف تُكمّل المهارات والأدوات بعضهما: + +### النمط 1: مهارات فقط (خبرة المجال، بدون إجراءات مطلوبة) + +استخدم عندما يحتاج الوكيل لتعليمات محددة لكن لا يحتاج لاستدعاء خدمات خارجية: + +```python +agent = Agent( + role="Technical Writer", + goal="Write clear API documentation", + backstory="Expert technical writer", + skills=["./skills/api-docs-style"], # إرشادات وقوالب الكتابة + # لا حاجة لأدوات — الوكيل يكتب بناءً على السياق المقدم +) +``` + +### النمط 2: أدوات فقط (إجراءات، بدون خبرة خاصة) + +استخدم عندما يحتاج الوكيل لاتخاذ إجراءات لكن لا يحتاج لتعليمات مجال محددة: + +```python +from crewai_tools import SerperDevTool, ScrapeWebsiteTool + +agent = Agent( + role="Web Researcher", + goal="Find information about a topic", + backstory="Skilled at finding information online", + tools=[SerperDevTool(), ScrapeWebsiteTool()], # يمكنه البحث والاستخراج + # لا حاجة لمهارات — البحث العام لا يحتاج إرشادات خاصة +) +``` + +### النمط 3: مهارات + أدوات (خبرة وإجراءات) + +النمط الأكثر شيوعًا في العالم الحقيقي. المهارة توفر *كيف* تقترب من العمل؛ الأدوات توفر *ما* يمكن للوكيل فعله: + +```python +from crewai_tools import SerperDevTool, FileReadTool, CodeInterpreterTool + +analyst = Agent( + role="Security Analyst", + goal="Audit infrastructure for vulnerabilities", + backstory="Expert in cloud security and compliance", + skills=["./skills/security-audit"], # منهجية وقوائم تحقق التدقيق + tools=[ + SerperDevTool(), # البحث عن ثغرات معروفة + FileReadTool(), # قراءة ملفات التكوين + CodeInterpreterTool(), # تشغيل سكربتات التحليل + ], +) +``` + +### النمط 4: مهارات + MCP + +المهارات تعمل مع خوادم MCP بنفس الطريقة التي تعمل بها مع الأدوات: + +```python +agent = Agent( + role="Data Analyst", + goal="Analyze customer data and generate reports", + backstory="Expert data analyst with strong statistical background", + skills=["./skills/data-analysis"], # منهجية التحليل + mcps=["https://data-warehouse.example.com/sse"], # وصول بيانات عن بُعد +) +``` + +### النمط 5: مهارات + تطبيقات + +المهارات يمكن أن توجّه كيف يستخدم الوكيل تكاملات المنصة: + +```python +agent = Agent( + role="Customer Support Agent", + goal="Respond to customer inquiries professionally", + backstory="Experienced support representative", + skills=["./skills/support-playbook"], # قوالب الردود وقواعد التصعيد + apps=["gmail", "zendesk"], # يمكنه إرسال رسائل بريد وتحديث التذاكر +) +``` + +--- + +## المهارات على مستوى الطاقم + +يمكن تعيين المهارات على الطاقم لتُطبّق على **جميع الوكلاء**: + +```python +from crewai import Crew + +crew = Crew( + agents=[researcher, writer, reviewer], + tasks=[research_task, write_task, review_task], + skills=["./skills"], # جميع الوكلاء يحصلون على هذه المهارات +) +``` + +المهارات على مستوى الوكيل لها الأولوية — إذا تم اكتشاف نفس المهارة في كلا المستويين، يتم استخدام نسخة الوكيل. + +--- + +## تنسيق SKILL.md + +```markdown +--- +name: my-skill +description: وصف قصير لما تفعله هذه المهارة ومتى تُستخدم. +license: Apache-2.0 # اختياري +compatibility: crewai>=0.1.0 # اختياري +metadata: # اختياري + author: your-name + version: "1.0" +allowed-tools: web-search file-read # اختياري، تجريبي +--- + +التعليمات للوكيل تُكتب هنا. يتم حقن محتوى Markdown هذا +في إرشادات الوكيل عند تفعيل المهارة. +``` + +### حقول البيانات الوصفية + +| الحقل | مطلوب | الوصف | +| :-------------- | :------- | :----------------------------------------------------------------------- | +| `name` | نعم | 1-64 حرف. أحرف صغيرة أبجدية رقمية وشرطات. يجب أن يطابق اسم المجلد. | +| `description` | نعم | 1-1024 حرف. يصف ما تفعله المهارة ومتى تُستخدم. | +| `license` | لا | اسم الترخيص أو مرجع لملف ترخيص مضمّن. | +| `compatibility` | لا | حد أقصى 500 حرف. متطلبات البيئة (منتجات، حزم، شبكة). | +| `metadata` | لا | تعيين مفتاح-قيمة نصي عشوائي. | +| `allowed-tools` | لا | قائمة أدوات معتمدة مسبقًا مفصولة بمسافات. تجريبي. | + +--- ## هيكل المجلد @@ -21,79 +223,25 @@ my-skill/ └── assets/ # اختياري — ملفات ثابتة (إعدادات، بيانات) ``` -يجب أن يتطابق اسم المجلد مع حقل `name` في `SKILL.md`. +يجب أن يتطابق اسم المجلد مع حقل `name` في `SKILL.md`. مجلدات `scripts/` و `references/` و `assets/` متاحة في مسار المهارة `path` للوكلاء الذين يحتاجون للإشارة إلى الملفات مباشرة. -## تنسيق 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")) + +# تفعيلها (تحميل محتوى SKILL.md الكامل) activated = [activate_skill(s) for s in skills] +# تمرير إلى وكيل agent = Agent( role="Researcher", goal="Find relevant information", @@ -102,13 +250,57 @@ agent = Agent( ) ``` +--- + ## كيف يتم تحميل المهارات -يتم تحميل المهارات تدريجيًا — فقط البيانات المطلوبة في كل مرحلة يتم قراءتها: +تستخدم المهارات **الكشف التدريجي** — تحمّل فقط ما هو مطلوب في كل مرحلة: -| المرحلة | ما يتم تحميله | متى | -| :--------------- | :------------------------------------------------ | :----------------- | -| الاكتشاف | الاسم، الوصف، حقول البيانات الوصفية | `discover_skills()` | -| التفعيل | نص محتوى SKILL.md الكامل | `activate_skill()` | +| المرحلة | ما يتم تحميله | متى | +| :--------- | :------------------------------------ | :------------------ | +| الاكتشاف | الاسم، الوصف، حقول البيانات الوصفية | `discover_skills()` | +| التفعيل | نص محتوى SKILL.md الكامل | `activate_skill()` | -أثناء التنفيذ العادي للوكيل، يتم اكتشاف المهارات وتفعيلها تلقائيًا. مجلدات `scripts/` و `references/` و `assets/` متاحة في مسار المهارة `path` للوكلاء الذين يحتاجون للإشارة إلى الملفات مباشرة. +أثناء التنفيذ العادي للوكيل (تمرير مسارات المجلدات عبر `skills=["./skills"]`)، يتم اكتشاف المهارات وتفعيلها تلقائيًا. التحميل التدريجي مهم فقط عند استخدام الواجهة البرمجية. + +--- + +## المهارات مقابل المعرفة + +كلا المهارات والمعرفة تُعدّل إرشادات الوكيل، لكنهما يخدمان أغراضًا مختلفة: + +| الجانب | المهارات | المعرفة | +| :--- | :--- | :--- | +| **ما توفره** | تعليمات، إجراءات، إرشادات | حقائق، بيانات، معلومات | +| **كيف تُخزّن** | ملفات Markdown (SKILL.md) | مُضمّنة في مخزن متجهي (ChromaDB) | +| **كيف تُسترجع** | يتم حقن المحتوى الكامل في الإرشادات | البحث الدلالي يجد الأجزاء ذات الصلة | +| **الأفضل لـ** | المنهجيات، قوائم التحقق، أدلة الأسلوب | مستندات الشركة، معلومات المنتج، بيانات مرجعية | +| **يُعيّن عبر** | `skills=["./skills"]` | `knowledge_sources=[source]` | + +**القاعدة العامة:** إذا كان الوكيل يحتاج لاتباع *عملية*، استخدم مهارة. إذا كان يحتاج للرجوع إلى *بيانات*، استخدم المعرفة. + +--- + +## الأسئلة الشائعة + + + + يعتمد على حالة الاستخدام. المهارات والأدوات **مستقلتان** — يمكنك استخدام أيّ منهما أو كليهما أو لا شيء. + + - **مهارات فقط**: عندما يحتاج الوكيل خبرة لكن لا يحتاج إجراءات خارجية (مثال: الكتابة بإرشادات أسلوبية) + - **أدوات فقط**: عندما يحتاج الوكيل إجراءات لكن لا يحتاج منهجية خاصة (مثال: بحث بسيط على الويب) + - **كليهما**: عندما يحتاج الوكيل خبرة وإجراءات (مثال: تدقيق أمني بقوائم تحقق محددة وقدرة على فحص الكود) + + + + **لا.** حقل `allowed-tools` في SKILL.md هو بيانات وصفية تجريبية فقط — لا يُنشئ أو يحقن أي أدوات. يجب عليك دائمًا تعيين الأدوات بشكل منفصل عبر `tools=[]` أو `mcps=[]` أو `apps=[]`. + + + + المهارة على مستوى الوكيل لها الأولوية. يتم إزالة التكرار حسب الاسم — مهارات الوكيل تُعالج أولاً، لذا إذا ظهر نفس اسم المهارة في كلا المستويين، تُستخدم نسخة الوكيل. + + + + هناك تحذير ناعم عند 50,000 حرف، لكن بدون حد صارم. حافظ على تركيز المهارات وإيجازها للحصول على أفضل النتائج — الحقن الكبيرة في الإرشادات قد تُشتت انتباه الوكيل. + + diff --git a/docs/ar/concepts/tools.mdx b/docs/ar/concepts/tools.mdx index 4a0226145..8b1e07aa1 100644 --- a/docs/ar/concepts/tools.mdx +++ b/docs/ar/concepts/tools.mdx @@ -10,6 +10,10 @@ mode: "wide" تُمكّن أدوات CrewAI الوكلاء بقدرات تتراوح من البحث على الويب وتحليل البيانات إلى التعاون وتفويض المهام بين الزملاء. توضح هذه الوثائق كيفية إنشاء هذه الأدوات ودمجها والاستفادة منها ضمن إطار عمل CrewAI، بما في ذلك التركيز على أدوات التعاون. + + الأدوات تمنح الوكلاء **دوال قابلة للاستدعاء** لاتخاذ إجراءات. تعمل جنبًا إلى جنب مع [MCP](/ar/mcp/overview) (خوادم أدوات عن بُعد) و[التطبيقات](/ar/concepts/agent-capabilities) (تكاملات المنصة) و[المهارات](/ar/concepts/skills) (خبرة المجال) و[المعرفة](/ar/concepts/knowledge) (حقائق مُسترجعة). راجع نظرة عامة على [قدرات الوكيل](/ar/concepts/agent-capabilities) لفهم متى تستخدم كل نوع. + + ## ما هي الأداة؟ الأداة في CrewAI هي مهارة أو وظيفة يمكن للوكلاء استخدامها لأداء إجراءات مختلفة. diff --git a/docs/docs.json b/docs/docs.json index bdc938c53..d4b927170 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -150,6 +150,7 @@ "group": "Core Concepts", "pages": [ "en/concepts/agents", + "en/concepts/agent-capabilities", "en/concepts/tasks", "en/concepts/crews", "en/concepts/flows", @@ -3462,6 +3463,7 @@ "group": "Conceitos-Chave", "pages": [ "pt-BR/concepts/agents", + "pt-BR/concepts/agent-capabilities", "pt-BR/concepts/tasks", "pt-BR/concepts/crews", "pt-BR/concepts/flows", @@ -6669,6 +6671,7 @@ "pages": [ "ko/concepts/agents", "ko/concepts/tasks", + "ko/concepts/agent-capabilities", "ko/concepts/crews", "ko/concepts/flows", "ko/concepts/production-architecture", @@ -9958,6 +9961,7 @@ "group": "\u0627\u0644\u0645\u0641\u0627\u0647\u064a\u0645 \u0627\u0644\u0623\u0633\u0627\u0633\u064a\u0629", "pages": [ "ar/concepts/agents", + "ar/concepts/agent-capabilities", "ar/concepts/tasks", "ar/concepts/crews", "ar/concepts/flows", diff --git a/docs/en/concepts/agent-capabilities.mdx b/docs/en/concepts/agent-capabilities.mdx new file mode 100644 index 000000000..17e334e80 --- /dev/null +++ b/docs/en/concepts/agent-capabilities.mdx @@ -0,0 +1,147 @@ +--- +title: "Agent Capabilities" +description: "Understand the five ways to extend CrewAI agents: Tools, MCPs, Apps, Skills, and Knowledge." +icon: puzzle-piece +mode: "wide" +--- + +## Overview + +CrewAI agents can be extended with **five distinct capability types**, each serving a different purpose. Understanding when to use each one — and how they work together — is key to building effective agents. + + + + **Callable functions** — give agents the ability to take action. Web searches, file operations, API calls, code execution. + + + **Remote tool servers** — connect agents to external tool servers via the Model Context Protocol. Same effect as tools, but hosted externally. + + + **Platform integrations** — connect agents to SaaS apps (Gmail, Slack, Jira, Salesforce) via CrewAI's managed OAuth layer. + + + **Domain expertise** — inject instructions, guidelines, and reference material into agent prompts. Skills tell agents *how to think*. + + + **Retrieved facts** — provide agents with data from documents, files, and URLs via semantic search (RAG). Knowledge gives agents *what to know*. + + + +--- + +## The Key Distinction + +The most important thing to understand: **these capabilities fall into two categories**. + +### Action Capabilities (Tools, MCPs, Apps) + +These give agents the ability to **do things** — call APIs, read files, search the web, send emails. At execution time, all three resolve into the same internal format (`BaseTool` instances) and appear in a unified tool list the agent can call. + +```python +from crewai import Agent +from crewai_tools import SerperDevTool, FileReadTool + +agent = Agent( + role="Researcher", + goal="Find and compile market data", + backstory="Expert market analyst", + tools=[SerperDevTool(), FileReadTool()], # Local tools + mcps=["https://mcp.example.com/sse"], # Remote MCP server tools + apps=["gmail", "google_sheets"], # Platform integrations +) +``` + +### Context Capabilities (Skills, Knowledge) + +These modify the agent's **prompt** — injecting expertise, instructions, or retrieved data before the agent starts reasoning. They don't give agents new actions; they shape how agents think and what information they have access to. + +```python +from crewai import Agent + +agent = Agent( + role="Security Auditor", + goal="Audit cloud infrastructure for vulnerabilities", + backstory="Expert in cloud security with 10 years of experience", + skills=["./skills/security-audit"], # Domain instructions + knowledge_sources=[pdf_source, url_source], # Retrieved facts +) +``` + +--- + +## When to Use What + +| You need... | Use | Example | +| :------------------------------------------------ | :---------------- | :--------------------------------------- | +| Agent to search the web | **Tools** | `tools=[SerperDevTool()]` | +| Agent to call a remote API via MCP | **MCPs** | `mcps=["https://api.example.com/sse"]` | +| Agent to send emails via Gmail | **Apps** | `apps=["gmail"]` | +| Agent to follow specific procedures | **Skills** | `skills=["./skills/code-review"]` | +| Agent to reference company docs | **Knowledge** | `knowledge_sources=[pdf_source]` | +| Agent to search the web AND follow review guidelines | **Tools + Skills** | Use both together | + +--- + +## Combining Capabilities + +In practice, agents often use **multiple capability types together**. Here's a realistic example: + +```python +from crewai import Agent +from crewai_tools import SerperDevTool, FileReadTool, CodeInterpreterTool + +# A fully-equipped research agent +researcher = Agent( + role="Senior Research Analyst", + goal="Produce comprehensive market analysis reports", + backstory="Expert analyst with deep industry knowledge", + + # ACTION: What the agent can DO + tools=[ + SerperDevTool(), # Search the web + FileReadTool(), # Read local files + CodeInterpreterTool(), # Run Python code for analysis + ], + mcps=["https://data-api.example.com/sse"], # Access remote data API + apps=["google_sheets"], # Write to Google Sheets + + # CONTEXT: What the agent KNOWS + skills=["./skills/research-methodology"], # How to conduct research + knowledge_sources=[company_docs], # Company-specific data +) +``` + +--- + +## Comparison Table + +| Feature | Tools | MCPs | Apps | Skills | Knowledge | +| :--- | :---: | :---: | :---: | :---: | :---: | +| **Gives agent actions** | ✅ | ✅ | ✅ | ❌ | ❌ | +| **Modifies prompt** | ❌ | ❌ | ❌ | ✅ | ✅ | +| **Requires code** | Yes | Config only | Config only | Markdown only | Config only | +| **Runs locally** | Yes | Depends | No (AMP API) | N/A | Yes | +| **Needs API keys** | Per tool | Per server | OAuth via AMP | No | Embedder only | +| **Set on Agent** | `tools=[]` | `mcps=[]` | `apps=[]` | `skills=[]` | `knowledge_sources=[]` | +| **Set on Crew** | ❌ | ❌ | ❌ | `skills=[]` | `knowledge_sources=[]` | + +--- + +## Deep Dives + +Ready to learn more about each capability type? + + + + Create custom tools, use the 75+ OSS catalog, configure caching and async execution. + + + Connect to MCP servers via stdio, SSE, or HTTP. Filter tools, configure auth. + + + Build skill packages with SKILL.md, inject domain expertise, use progressive disclosure. + + + Add knowledge from PDFs, CSVs, URLs, and more. Configure embedders and retrieval. + + diff --git a/docs/en/concepts/skills.mdx b/docs/en/concepts/skills.mdx index 90a7f822d..d88602b84 100644 --- a/docs/en/concepts/skills.mdx +++ b/docs/en/concepts/skills.mdx @@ -1,27 +1,186 @@ --- title: Skills -description: Filesystem-based skill packages that inject context into agent prompts. +description: Filesystem-based skill packages that inject domain expertise and instructions into agent prompts. icon: bolt mode: "wide" --- ## Overview -Skills are self-contained directories that provide agents with domain-specific instructions, references, and assets. Each skill is defined by a `SKILL.md` file with YAML frontmatter and a markdown body. +Skills are self-contained directories that provide agents with **domain-specific instructions, guidelines, and reference material**. Each skill is defined by a `SKILL.md` file with YAML frontmatter and a markdown body. -Skills use **progressive disclosure** — metadata is loaded first, full instructions only when activated, and resource catalogs only when needed. +When activated, a skill's instructions are injected directly into the agent's task prompt — giving the agent expertise without requiring any code changes. -## Directory Structure + +**Skills are NOT tools.** This is the most common point of confusion. + +- **Skills** inject *instructions and context* into the agent's prompt. They tell the agent *how to think* about a problem. +- **Tools** give the agent *callable functions* to take action (search, read files, call APIs). + +You often need **both**: skills for expertise, tools for action. They are configured independently and complement each other. + + +--- + +## Quick Start + +### 1. Create a Skill Directory ``` -my-skill/ -├── SKILL.md # Required — frontmatter + instructions -├── scripts/ # Optional — executable scripts -├── references/ # Optional — reference documents -└── assets/ # Optional — static files (configs, data) +skills/ +└── code-review/ + ├── SKILL.md # Required — instructions + ├── references/ # Optional — reference docs + │ └── style-guide.md + └── scripts/ # Optional — executable scripts ``` -The directory name must match the `name` field in `SKILL.md`. +### 2. Write Your SKILL.md + +```markdown +--- +name: code-review +description: Guidelines for conducting thorough code reviews with focus on security and performance. +metadata: + author: your-team + version: "1.0" +--- + +## Code Review Guidelines + +When reviewing code, follow this checklist: + +1. **Security**: Check for injection vulnerabilities, auth bypasses, and data exposure +2. **Performance**: Look for N+1 queries, unnecessary allocations, and blocking calls +3. **Readability**: Ensure clear naming, appropriate comments, and consistent style +4. **Testing**: Verify adequate test coverage for new functionality + +### Severity Levels +- **Critical**: Security vulnerabilities, data loss risks → block merge +- **Major**: Performance issues, logic errors → request changes +- **Minor**: Style issues, naming suggestions → approve with comments +``` + +### 3. Attach to an Agent + +```python +from crewai import Agent +from crewai_tools import GithubSearchTool, FileReadTool + +reviewer = Agent( + role="Senior Code Reviewer", + goal="Review pull requests for quality and security issues", + backstory="Staff engineer with expertise in secure coding practices.", + skills=["./skills"], # Injects review guidelines + tools=[GithubSearchTool(), FileReadTool()], # Lets agent read code +) +``` + +The agent now has both **expertise** (from the skill) and **capabilities** (from the tools). + +--- + +## Skills + Tools: Working Together + +Here are common patterns showing how skills and tools complement each other: + +### Pattern 1: Skills Only (Domain Expertise, No Actions Needed) + +Use when the agent needs specific instructions but doesn't need to call external services: + +```python +agent = Agent( + role="Technical Writer", + goal="Write clear API documentation", + backstory="Expert technical writer", + skills=["./skills/api-docs-style"], # Writing guidelines and templates + # No tools needed — agent writes based on provided context +) +``` + +### Pattern 2: Tools Only (Actions, No Special Expertise) + +Use when the agent needs to take action but doesn't need domain-specific instructions: + +```python +from crewai_tools import SerperDevTool, ScrapeWebsiteTool + +agent = Agent( + role="Web Researcher", + goal="Find information about a topic", + backstory="Skilled at finding information online", + tools=[SerperDevTool(), ScrapeWebsiteTool()], # Can search and scrape + # No skills needed — general research doesn't need special guidelines +) +``` + +### Pattern 3: Skills + Tools (Expertise AND Actions) + +The most common real-world pattern. The skill provides *how* to approach the work; tools provide *what* the agent can do: + +```python +from crewai_tools import SerperDevTool, FileReadTool, CodeInterpreterTool + +analyst = Agent( + role="Security Analyst", + goal="Audit infrastructure for vulnerabilities", + backstory="Expert in cloud security and compliance", + skills=["./skills/security-audit"], # Audit methodology and checklists + tools=[ + SerperDevTool(), # Research known vulnerabilities + FileReadTool(), # Read config files + CodeInterpreterTool(), # Run analysis scripts + ], +) +``` + +### Pattern 4: Skills + MCPs + +Skills work alongside MCP servers the same way they work with tools: + +```python +agent = Agent( + role="Data Analyst", + goal="Analyze customer data and generate reports", + backstory="Expert data analyst with strong statistical background", + skills=["./skills/data-analysis"], # Analysis methodology + mcps=["https://data-warehouse.example.com/sse"], # Remote data access +) +``` + +### Pattern 5: Skills + Apps + +Skills can guide how an agent uses platform integrations: + +```python +agent = Agent( + role="Customer Support Agent", + goal="Respond to customer inquiries professionally", + backstory="Experienced support representative", + skills=["./skills/support-playbook"], # Response templates and escalation rules + apps=["gmail", "zendesk"], # Can send emails and update tickets +) +``` + +--- + +## Crew-Level Skills + +Skills can be set on a crew to apply to **all agents**: + +```python +from crewai import Crew + +crew = Crew( + agents=[researcher, writer, reviewer], + tasks=[research_task, write_task, review_task], + skills=["./skills"], # All agents get these skills +) +``` + +Agent-level skills take priority — if the same skill is discovered at both levels, the agent's version is used. + +--- ## SKILL.md Format @@ -34,7 +193,7 @@ compatibility: crewai>=0.1.0 # optional metadata: # optional author: your-name version: "1.0" -allowed-tools: web-search file-read # optional, space-delimited +allowed-tools: web-search file-read # optional, experimental --- Instructions for the agent go here. This markdown body is injected @@ -43,57 +202,46 @@ into the agent's prompt when the skill is activated. ### Frontmatter Fields -| Field | Required | Constraints | +| Field | Required | Description | | :-------------- | :------- | :----------------------------------------------------------------------- | -| `name` | Yes | 1–64 chars. Lowercase alphanumeric and hyphens. No leading/trailing/consecutive hyphens. Must match directory name. | +| `name` | Yes | 1–64 chars. Lowercase alphanumeric and hyphens. Must match directory name. | | `description` | Yes | 1–1024 chars. Describes what the skill does and when to use it. | | `license` | No | License name or reference to a bundled license file. | | `compatibility` | No | Max 500 chars. Environment requirements (products, packages, network). | | `metadata` | No | Arbitrary string key-value mapping. | | `allowed-tools` | No | Space-delimited list of pre-approved tools. Experimental. | -## Usage +--- -### Agent-level Skills +## Directory Structure -Pass skill directory paths to an agent: - -```python -from crewai import Agent - -agent = Agent( - role="Researcher", - goal="Find relevant information", - backstory="An expert researcher.", - skills=["./skills"], # discovers all skills in this directory -) +``` +my-skill/ +├── SKILL.md # Required — frontmatter + instructions +├── scripts/ # Optional — executable scripts +├── references/ # Optional — reference documents +└── assets/ # Optional — static files (configs, data) ``` -### Crew-level Skills +The directory name must match the `name` field in `SKILL.md`. The `scripts/`, `references/`, and `assets/` directories are available on the skill's `path` for agents that need to reference files directly. -Skill paths on a crew are merged into every agent: +--- -```python -from crewai import Crew +## Pre-loading Skills -crew = Crew( - agents=[agent], - tasks=[task], - skills=["./skills"], -) -``` - -### Pre-loaded Skills - -You can also pass `Skill` objects directly: +For more control, you can discover and activate skills programmatically: ```python from pathlib import Path from crewai.skills import discover_skills, activate_skill +# Discover all skills in a directory skills = discover_skills(Path("./skills")) + +# Activate them (loads full SKILL.md body) activated = [activate_skill(s) for s in skills] +# Pass to an agent agent = Agent( role="Researcher", goal="Find relevant information", @@ -102,14 +250,57 @@ agent = Agent( ) ``` +--- + ## How Skills Are Loaded -Skills load progressively — only the data needed at each stage is read: +Skills use **progressive disclosure** — only loading what's needed at each stage: -| Stage | What's loaded | When | -| :--------------- | :------------------------------------------------ | :----------------- | -| Discovery | Name, description, frontmatter fields | `discover_skills()` | -| Activation | Full SKILL.md body text | `activate_skill()` | +| Stage | What's loaded | When | +| :--------- | :------------------------------------ | :------------------ | +| Discovery | Name, description, frontmatter fields | `discover_skills()` | +| Activation | Full SKILL.md body text | `activate_skill()` | -During normal agent execution, skills are automatically discovered and activated. The `scripts/`, `references/`, and `assets/` directories are available on the skill's `path` for agents that need to reference files directly. +During normal agent execution (passing directory paths via `skills=["./skills"]`), skills are automatically discovered and activated. The progressive loading only matters when using the programmatic API. +--- + +## Skills vs Knowledge + +Both skills and knowledge modify the agent's prompt, but they serve different purposes: + +| Aspect | Skills | Knowledge | +| :--- | :--- | :--- | +| **What it provides** | Instructions, procedures, guidelines | Facts, data, information | +| **How it's stored** | Markdown files (SKILL.md) | Embedded in vector store (ChromaDB) | +| **How it's retrieved** | Entire body injected into prompt | Semantic search finds relevant chunks | +| **Best for** | Methodology, checklists, style guides | Company docs, product info, reference data | +| **Set via** | `skills=["./skills"]` | `knowledge_sources=[source]` | + +**Rule of thumb:** If the agent needs to follow a *process*, use a skill. If the agent needs to reference *data*, use knowledge. + +--- + +## Common Questions + + + + It depends on your use case. Skills and tools are **independent** — you can use either, both, or neither. + + - **Skills alone**: When the agent needs expertise but no external actions (e.g., writing with style guidelines) + - **Tools alone**: When the agent needs actions but no special methodology (e.g., simple web search) + - **Both**: When the agent needs expertise AND actions (e.g., security audit with specific checklists AND ability to scan code) + + + + **No.** The `allowed-tools` field in SKILL.md is experimental metadata only — it does not provision or inject any tools. You must always set tools separately via `tools=[]`, `mcps=[]`, or `apps=[]`. + + + + The agent-level skill takes priority. Skills are deduplicated by name — the agent's skills are processed first, so if the same skill name appears at both levels, the agent's version is used. + + + + There's a soft warning at 50,000 characters, but no hard limit. Keep skills focused and concise for best results — large prompt injections can dilute the agent's attention. + + diff --git a/docs/en/concepts/tools.mdx b/docs/en/concepts/tools.mdx index 1023d1281..f634c9f95 100644 --- a/docs/en/concepts/tools.mdx +++ b/docs/en/concepts/tools.mdx @@ -10,6 +10,10 @@ mode: "wide" CrewAI tools empower agents with capabilities ranging from web searching and data analysis to collaboration and delegating tasks among coworkers. This documentation outlines how to create, integrate, and leverage these tools within the CrewAI framework, including a new focus on collaboration tools. + + Tools give agents **callable functions** to take action. They work alongside [MCPs](/en/mcp/overview) (remote tool servers), [Apps](/en/concepts/agent-capabilities) (platform integrations), [Skills](/en/concepts/skills) (domain expertise), and [Knowledge](/en/concepts/knowledge) (retrieved facts). See the [Agent Capabilities](/en/concepts/agent-capabilities) overview to understand when to use each. + + ## What is a Tool? A tool in CrewAI is a skill or function that agents can utilize to perform various actions. diff --git a/docs/ko/concepts/agent-capabilities.mdx b/docs/ko/concepts/agent-capabilities.mdx new file mode 100644 index 000000000..524533af2 --- /dev/null +++ b/docs/ko/concepts/agent-capabilities.mdx @@ -0,0 +1,147 @@ +--- +title: "에이전트 기능" +description: "CrewAI 에이전트를 확장하는 다섯 가지 방법 이해하기: 도구, MCP, 앱, 스킬, 지식." +icon: puzzle-piece +mode: "wide" +--- + +## 개요 + +CrewAI 에이전트는 **다섯 가지 고유한 기능 유형**으로 확장할 수 있으며, 각각 다른 목적을 가지고 있습니다. 각 유형을 언제 사용해야 하는지, 그리고 어떻게 함께 작동하는지 이해하는 것이 효과적인 에이전트를 구축하는 핵심입니다. + + + + **호출 가능한 함수** — 에이전트가 행동을 취할 수 있게 합니다. 웹 검색, 파일 작업, API 호출, 코드 실행. + + + **원격 도구 서버** — Model Context Protocol을 통해 에이전트를 외부 도구 서버에 연결합니다. 도구와 같은 효과이지만 외부에서 호스팅됩니다. + + + **플랫폼 통합** — CrewAI의 관리형 OAuth 레이어를 통해 에이전트를 SaaS 앱(Gmail, Slack, Jira, Salesforce)에 연결합니다. + + + **도메인 전문성** — 에이전트 프롬프트에 지침, 가이드라인 및 참조 자료를 주입합니다. 스킬은 에이전트에게 *어떻게 생각할지*를 알려줍니다. + + + **검색된 사실** — 시맨틱 검색(RAG)을 통해 문서, 파일 및 URL에서 에이전트에게 데이터를 제공합니다. 지식은 에이전트에게 *무엇을 알아야 하는지*를 제공합니다. + + + +--- + +## 핵심 구분 + +가장 중요한 점: **이 기능들은 두 가지 범주로 나뉩니다**. + +### 액션 기능 (도구, MCP, 앱) + +에이전트에게 **무언가를 할 수 있는** 능력을 부여합니다 — API 호출, 파일 읽기, 웹 검색, 이메일 전송. 실행 시점에 세 가지 모두 동일한 내부 형식(`BaseTool` 인스턴스)으로 변환되며, 에이전트가 호출할 수 있는 통합 도구 목록에 나타납니다. + +```python +from crewai import Agent +from crewai_tools import SerperDevTool, FileReadTool + +agent = Agent( + role="Researcher", + goal="Find and compile market data", + backstory="Expert market analyst", + tools=[SerperDevTool(), FileReadTool()], # 로컬 도구 + mcps=["https://mcp.example.com/sse"], # 원격 MCP 서버 도구 + apps=["gmail", "google_sheets"], # 플랫폼 통합 +) +``` + +### 컨텍스트 기능 (스킬, 지식) + +에이전트의 **프롬프트**를 수정합니다 — 에이전트가 추론을 시작하기 전에 전문성, 지침 또는 검색된 데이터를 주입합니다. 에이전트에게 새로운 액션을 제공하는 것이 아니라, 에이전트가 어떻게 생각하고 어떤 정보에 접근할 수 있는지를 형성합니다. + +```python +from crewai import Agent + +agent = Agent( + role="Security Auditor", + goal="Audit cloud infrastructure for vulnerabilities", + backstory="Expert in cloud security with 10 years of experience", + skills=["./skills/security-audit"], # 도메인 지침 + knowledge_sources=[pdf_source, url_source], # 검색된 사실 +) +``` + +--- + +## 언제 무엇을 사용할까 + +| 필요한 것... | 사용할 것 | 예시 | +| :------------------------------------------------------- | :---------------- | :--------------------------------------- | +| 에이전트가 웹을 검색 | **도구** | `tools=[SerperDevTool()]` | +| 에이전트가 MCP를 통해 원격 API 호출 | **MCP** | `mcps=["https://api.example.com/sse"]` | +| 에이전트가 Gmail로 이메일 전송 | **앱** | `apps=["gmail"]` | +| 에이전트가 특정 절차를 따름 | **스킬** | `skills=["./skills/code-review"]` | +| 에이전트가 회사 문서 참조 | **지식** | `knowledge_sources=[pdf_source]` | +| 에이전트가 웹 검색 AND 리뷰 가이드라인 준수 | **도구 + 스킬** | 둘 다 함께 사용 | + +--- + +## 기능 조합하기 + +실제로 에이전트는 종종 **여러 기능 유형을 함께** 사용합니다. 현실적인 예시입니다: + +```python +from crewai import Agent +from crewai_tools import SerperDevTool, FileReadTool, CodeInterpreterTool + +# 완전히 갖춘 리서치 에이전트 +researcher = Agent( + role="Senior Research Analyst", + goal="Produce comprehensive market analysis reports", + backstory="Expert analyst with deep industry knowledge", + + # 액션: 에이전트가 할 수 있는 것 + tools=[ + SerperDevTool(), # 웹 검색 + FileReadTool(), # 로컬 파일 읽기 + CodeInterpreterTool(), # 분석을 위한 Python 코드 실행 + ], + mcps=["https://data-api.example.com/sse"], # 원격 데이터 API 접근 + apps=["google_sheets"], # Google Sheets에 쓰기 + + # 컨텍스트: 에이전트가 아는 것 + skills=["./skills/research-methodology"], # 연구 수행 방법 + knowledge_sources=[company_docs], # 회사 특화 데이터 +) +``` + +--- + +## 비교 테이블 + +| 특성 | 도구 | MCP | 앱 | 스킬 | 지식 | +| :--- | :---: | :---: | :---: | :---: | :---: | +| **에이전트에게 액션 부여** | ✅ | ✅ | ✅ | ❌ | ❌ | +| **프롬프트 수정** | ❌ | ❌ | ❌ | ✅ | ✅ | +| **코드 필요** | 예 | 설정만 | 설정만 | 마크다운만 | 설정만 | +| **로컬 실행** | 예 | 경우에 따라 | 아니오 (AMP API) | N/A | 예 | +| **API 키 필요** | 도구별 | 서버별 | AMP를 통한 OAuth | 아니오 | 임베더만 | +| **Agent에 설정** | `tools=[]` | `mcps=[]` | `apps=[]` | `skills=[]` | `knowledge_sources=[]` | +| **Crew에 설정** | ❌ | ❌ | ❌ | `skills=[]` | `knowledge_sources=[]` | + +--- + +## 상세 가이드 + +각 기능 유형에 대해 더 알아볼 준비가 되셨나요? + + + + 맞춤형 도구 생성, 75개 이상의 OSS 카탈로그 사용, 캐싱 및 비동기 실행 설정. + + + stdio, SSE 또는 HTTP를 통해 MCP 서버에 연결. 도구 필터링, 인증 설정. + + + SKILL.md로 스킬 패키지 구축, 도메인 전문성 주입, 점진적 공개 사용. + + + PDF, CSV, URL 등에서 지식 추가. 임베더 및 검색 설정. + + diff --git a/docs/ko/concepts/skills.mdx b/docs/ko/concepts/skills.mdx index a6361bce2..ea1009dc0 100644 --- a/docs/ko/concepts/skills.mdx +++ b/docs/ko/concepts/skills.mdx @@ -1,27 +1,186 @@ --- title: 스킬 -description: 에이전트 프롬프트에 컨텍스트를 주입하는 파일 시스템 기반 스킬 패키지. +description: 에이전트 프롬프트에 도메인 전문성과 지침을 주입하는 파일 시스템 기반 스킬 패키지. icon: bolt mode: "wide" --- ## 개요 -스킬은 에이전트에게 도메인별 지침, 참조 자료, 에셋을 제공하는 자체 포함 디렉터리입니다. 각 스킬은 YAML 프론트매터와 마크다운 본문이 포함된 `SKILL.md` 파일로 정의됩니다. +스킬은 에이전트에게 **도메인별 지침, 가이드라인 및 참조 자료**를 제공하는 자체 포함 디렉터리입니다. 각 스킬은 YAML 프론트매터와 마크다운 본문이 포함된 `SKILL.md` 파일로 정의됩니다. -스킬은 **점진적 공개**를 사용합니다 — 메타데이터가 먼저 로드되고, 활성화 시에만 전체 지침이 로드되며, 필요할 때만 리소스 카탈로그가 로드됩니다. +활성화되면 스킬의 지침이 에이전트의 작업 프롬프트에 직접 주입됩니다 — 코드 변경 없이 에이전트에게 전문성을 부여합니다. -## 디렉터리 구조 + +**스킬은 도구가 아닙니다.** 이것이 가장 흔한 혼동 포인트입니다. + +- **스킬**은 에이전트의 프롬프트에 *지침과 컨텍스트*를 주입합니다. 에이전트에게 문제에 대해 *어떻게 생각할지*를 알려줍니다. +- **도구**는 에이전트에게 행동을 취할 수 있는 *호출 가능한 함수*를 제공합니다 (검색, 파일 읽기, API 호출). + +흔히 **둘 다** 필요합니다: 전문성을 위한 스킬과 행동을 위한 도구. 이들은 독립적으로 구성되며 서로 보완합니다. + + +--- + +## 빠른 시작 + +### 1. 스킬 디렉터리 생성 ``` -my-skill/ -├── SKILL.md # 필수 — 프론트매터 + 지침 -├── scripts/ # 선택 — 실행 가능한 스크립트 -├── references/ # 선택 — 참조 문서 -└── assets/ # 선택 — 정적 파일 (설정, 데이터) +skills/ +└── code-review/ + ├── SKILL.md # 필수 — 지침 + ├── references/ # 선택 — 참조 문서 + │ └── style-guide.md + └── scripts/ # 선택 — 실행 가능한 스크립트 ``` -디렉터리 이름은 `SKILL.md`의 `name` 필드와 일치해야 합니다. +### 2. SKILL.md 작성 + +```markdown +--- +name: code-review +description: Guidelines for conducting thorough code reviews with focus on security and performance. +metadata: + author: your-team + version: "1.0" +--- + +## 코드 리뷰 가이드라인 + +코드를 리뷰할 때 이 체크리스트를 따르세요: + +1. **보안**: 인젝션 취약점, 인증 우회, 데이터 노출 확인 +2. **성능**: N+1 쿼리, 불필요한 할당, 블로킹 호출 확인 +3. **가독성**: 명확한 네이밍, 적절한 주석, 일관된 스타일 보장 +4. **테스트**: 새로운 기능에 대한 적절한 테스트 커버리지 확인 + +### 심각도 수준 +- **크리티컬**: 보안 취약점, 데이터 손실 위험 → 머지 차단 +- **메이저**: 성능 문제, 로직 오류 → 변경 요청 +- **마이너**: 스타일 문제, 네이밍 제안 → 코멘트와 함께 승인 +``` + +### 3. 에이전트에 연결 + +```python +from crewai import Agent +from crewai_tools import GithubSearchTool, FileReadTool + +reviewer = Agent( + role="Senior Code Reviewer", + goal="Review pull requests for quality and security issues", + backstory="Staff engineer with expertise in secure coding practices.", + skills=["./skills"], # 리뷰 가이드라인 주입 + tools=[GithubSearchTool(), FileReadTool()], # 에이전트가 코드를 읽을 수 있게 함 +) +``` + +이제 에이전트는 **전문성** (스킬에서)과 **기능** (도구에서) 모두를 갖추게 됩니다. + +--- + +## 스킬 + 도구: 함께 작동하기 + +스킬과 도구가 어떻게 보완하는지 보여주는 일반적인 패턴입니다: + +### 패턴 1: 스킬만 (도메인 전문성, 액션 불필요) + +에이전트가 특정 지침이 필요하지만 외부 서비스를 호출할 필요가 없을 때 사용: + +```python +agent = Agent( + role="Technical Writer", + goal="Write clear API documentation", + backstory="Expert technical writer", + skills=["./skills/api-docs-style"], # 작성 가이드라인 및 템플릿 + # 도구 불필요 — 에이전트가 제공된 컨텍스트를 기반으로 작성 +) +``` + +### 패턴 2: 도구만 (액션, 특별한 전문성 불필요) + +에이전트가 행동을 취해야 하지만 도메인별 지침이 필요 없을 때 사용: + +```python +from crewai_tools import SerperDevTool, ScrapeWebsiteTool + +agent = Agent( + role="Web Researcher", + goal="Find information about a topic", + backstory="Skilled at finding information online", + tools=[SerperDevTool(), ScrapeWebsiteTool()], # 검색 및 스크래핑 가능 + # 스킬 불필요 — 일반 연구에는 특별한 가이드라인이 필요 없음 +) +``` + +### 패턴 3: 스킬 + 도구 (전문성 AND 액션) + +가장 일반적인 실제 패턴. 스킬은 작업에 *어떻게* 접근할지를 제공하고, 도구는 에이전트가 *무엇을* 할 수 있는지를 제공합니다: + +```python +from crewai_tools import SerperDevTool, FileReadTool, CodeInterpreterTool + +analyst = Agent( + role="Security Analyst", + goal="Audit infrastructure for vulnerabilities", + backstory="Expert in cloud security and compliance", + skills=["./skills/security-audit"], # 감사 방법론 및 체크리스트 + tools=[ + SerperDevTool(), # 알려진 취약점 조사 + FileReadTool(), # 설정 파일 읽기 + CodeInterpreterTool(), # 분석 스크립트 실행 + ], +) +``` + +### 패턴 4: 스킬 + MCP + +스킬은 도구와 마찬가지로 MCP 서버와 함께 작동합니다: + +```python +agent = Agent( + role="Data Analyst", + goal="Analyze customer data and generate reports", + backstory="Expert data analyst with strong statistical background", + skills=["./skills/data-analysis"], # 분석 방법론 + mcps=["https://data-warehouse.example.com/sse"], # 원격 데이터 접근 +) +``` + +### 패턴 5: 스킬 + 앱 + +스킬은 에이전트가 플랫폼 통합을 사용하는 방법을 안내할 수 있습니다: + +```python +agent = Agent( + role="Customer Support Agent", + goal="Respond to customer inquiries professionally", + backstory="Experienced support representative", + skills=["./skills/support-playbook"], # 응답 템플릿 및 에스컬레이션 규칙 + apps=["gmail", "zendesk"], # 이메일 전송 및 티켓 업데이트 가능 +) +``` + +--- + +## 크루 레벨 스킬 + +스킬을 크루에 설정하여 **모든 에이전트**에 적용할 수 있습니다: + +```python +from crewai import Crew + +crew = Crew( + agents=[researcher, writer, reviewer], + tasks=[research_task, write_task, review_task], + skills=["./skills"], # 모든 에이전트가 이 스킬을 받음 +) +``` + +에이전트 레벨 스킬이 우선합니다 — 동일한 스킬이 양쪽 레벨에서 발견되면 에이전트의 버전이 사용됩니다. + +--- ## SKILL.md 형식 @@ -34,7 +193,7 @@ compatibility: crewai>=0.1.0 # 선택 metadata: # 선택 author: your-name version: "1.0" -allowed-tools: web-search file-read # 선택, 공백으로 구분 +allowed-tools: web-search file-read # 선택, 실험적 --- 에이전트를 위한 지침이 여기에 들어갑니다. 이 마크다운 본문은 @@ -43,57 +202,46 @@ allowed-tools: web-search file-read # 선택, 공백으로 구분 ### 프론트매터 필드 -| 필드 | 필수 | 제약 조건 | +| 필드 | 필수 | 설명 | | :-------------- | :----- | :----------------------------------------------------------------------- | -| `name` | 예 | 1–64자. 소문자 영숫자와 하이픈. 선행/후행/연속 하이픈 불가. 디렉터리 이름과 일치 필수. | +| `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"], # 이 디렉터리의 모든 스킬을 검색 -) +``` +my-skill/ +├── SKILL.md # 필수 — 프론트매터 + 지침 +├── scripts/ # 선택 — 실행 가능한 스크립트 +├── references/ # 선택 — 참조 문서 +└── assets/ # 선택 — 정적 파일 (설정, 데이터) ``` -### 크루 레벨 스킬 +디렉터리 이름은 `SKILL.md`의 `name` 필드와 일치해야 합니다. `scripts/`, `references/`, `assets/` 디렉터리는 파일을 직접 참조해야 하는 에이전트를 위해 스킬의 `path`에서 사용할 수 있습니다. -크루의 스킬 경로는 모든 에이전트에 병합됩니다: +--- -```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")) + +# 활성화 (전체 SKILL.md 본문 로드) activated = [activate_skill(s) for s in skills] +# 에이전트에 전달 agent = Agent( role="Researcher", goal="Find relevant information", @@ -102,13 +250,57 @@ agent = Agent( ) ``` +--- + ## 스킬 로드 방식 -스킬은 점진적으로 로드됩니다 — 각 단계에서 필요한 데이터만 읽습니다: +스킬은 **점진적 공개**를 사용합니다 — 각 단계에서 필요한 것만 로드합니다: -| 단계 | 로드되는 내용 | 시점 | -| :--------------- | :------------------------------------------------ | :----------------- | -| 검색 | 이름, 설명, 프론트매터 필드 | `discover_skills()` | -| 활성화 | 전체 SKILL.md 본문 텍스트 | `activate_skill()` | +| 단계 | 로드되는 내용 | 시점 | +| :------- | :------------------------------------ | :------------------ | +| 검색 | 이름, 설명, 프론트매터 필드 | `discover_skills()` | +| 활성화 | 전체 SKILL.md 본문 텍스트 | `activate_skill()` | -일반적인 에이전트 실행 중에 스킬은 자동으로 검색되고 활성화됩니다. `scripts/`, `references/`, `assets/` 디렉터리는 파일을 직접 참조해야 하는 에이전트를 위해 스킬의 `path`에서 사용할 수 있습니다. +일반적인 에이전트 실행 중(`skills=["./skills"]`로 디렉터리 경로 전달 시) 스킬은 자동으로 검색되고 활성화됩니다. 점진적 로딩은 프로그래밍 API를 사용할 때만 관련됩니다. + +--- + +## 스킬 vs 지식 + +스킬과 지식 모두 에이전트의 프롬프트를 수정하지만, 서로 다른 목적을 가지고 있습니다: + +| 측면 | 스킬 | 지식 | +| :--- | :--- | :--- | +| **제공하는 것** | 지침, 절차, 가이드라인 | 사실, 데이터, 정보 | +| **저장 방식** | 마크다운 파일 (SKILL.md) | 벡터 스토어에 임베딩 (ChromaDB) | +| **검색 방식** | 전체 본문이 프롬프트에 주입 | 시맨틱 검색으로 관련 청크 찾기 | +| **적합한 용도** | 방법론, 체크리스트, 스타일 가이드 | 회사 문서, 제품 정보, 참조 데이터 | +| **설정 방법** | `skills=["./skills"]` | `knowledge_sources=[source]` | + +**경험 법칙:** 에이전트가 *프로세스*를 따라야 하면 스킬을 사용하세요. 에이전트가 *데이터*를 참조해야 하면 지식을 사용하세요. + +--- + +## 자주 묻는 질문 + + + + 사용 사례에 따라 다릅니다. 스킬과 도구는 **독립적**입니다 — 둘 중 하나, 둘 다, 또는 아무것도 사용하지 않을 수 있습니다. + + - **스킬만**: 에이전트가 전문성은 필요하지만 외부 액션이 필요 없을 때 (예: 스타일 가이드라인으로 작성) + - **도구만**: 에이전트가 액션은 필요하지만 특별한 방법론이 필요 없을 때 (예: 간단한 웹 검색) + - **둘 다**: 에이전트가 전문성 AND 액션이 필요할 때 (예: 특정 체크리스트로 보안 감사 AND 코드 스캔 기능) + + + + **아니요.** SKILL.md의 `allowed-tools` 필드는 실험적 메타데이터일 뿐 — 도구를 프로비저닝하거나 주입하지 않습니다. 항상 `tools=[]`, `mcps=[]` 또는 `apps=[]`를 통해 별도로 도구를 설정해야 합니다. + + + + 에이전트 레벨 스킬이 우선합니다. 스킬은 이름으로 중복 제거됩니다 — 에이전트의 스킬이 먼저 처리되므로, 같은 스킬 이름이 양쪽 레벨에 나타나면 에이전트의 버전이 사용됩니다. + + + + 50,000자에서 소프트 경고가 있지만 하드 리밋은 없습니다. 최상의 결과를 위해 스킬을 집중적이고 간결하게 유지하세요 — 너무 큰 프롬프트 주입은 에이전트의 주의를 분산시킬 수 있습니다. + + diff --git a/docs/ko/concepts/tools.mdx b/docs/ko/concepts/tools.mdx index 79dd29a60..de346e069 100644 --- a/docs/ko/concepts/tools.mdx +++ b/docs/ko/concepts/tools.mdx @@ -10,6 +10,10 @@ mode: "wide" CrewAI 도구는 에이전트에게 웹 검색, 데이터 분석부터 동료 간 협업 및 작업 위임에 이르기까지 다양한 기능을 제공합니다. 이 문서에서는 CrewAI 프레임워크 내에서 이러한 도구를 생성, 통합 및 활용하는 방법과, 협업 도구에 초점을 맞춘 새로운 기능에 대해 설명합니다. + + 도구는 에이전트에게 행동을 취할 수 있는 **호출 가능한 함수**를 제공합니다. [MCP](/ko/mcp/overview) (원격 도구 서버), [앱](/ko/concepts/agent-capabilities) (플랫폼 통합), [스킬](/ko/concepts/skills) (도메인 전문성), [지식](/ko/concepts/knowledge) (검색된 사실)과 함께 작동합니다. 각 유형을 언제 사용해야 하는지 알아보려면 [에이전트 기능](/ko/concepts/agent-capabilities) 개요를 참조하세요. + + ## Tool이란 무엇인가? CrewAI에서 tool은 에이전트가 다양한 작업을 수행하기 위해 활용할 수 있는 기술 또는 기능입니다. diff --git a/docs/pt-BR/concepts/agent-capabilities.mdx b/docs/pt-BR/concepts/agent-capabilities.mdx new file mode 100644 index 000000000..e7a378c08 --- /dev/null +++ b/docs/pt-BR/concepts/agent-capabilities.mdx @@ -0,0 +1,147 @@ +--- +title: "Capacidades do Agente" +description: "Entenda as cinco formas de estender agentes CrewAI: Ferramentas, MCPs, Apps, Skills e Knowledge." +icon: puzzle-piece +mode: "wide" +--- + +## Visão Geral + +Agentes CrewAI podem ser estendidos com **cinco tipos distintos de capacidades**, cada um servindo a um propósito diferente. Entender quando usar cada um — e como eles funcionam juntos — é fundamental para construir agentes eficazes. + + + + **Funções chamáveis** — permitem que agentes tomem ações. Buscas na web, operações com arquivos, chamadas de API, execução de código. + + + **Servidores de ferramentas remotos** — conectam agentes a servidores de ferramentas externos via Model Context Protocol. Mesmo efeito de ferramentas, mas hospedados externamente. + + + **Integrações com plataformas** — conectam agentes a aplicativos SaaS (Gmail, Slack, Jira, Salesforce) via camada OAuth gerenciada do CrewAI. + + + **Expertise de domínio** — injetam instruções, diretrizes e material de referência nos prompts dos agentes. Skills dizem aos agentes *como pensar*. + + + **Fatos recuperados** — fornecem aos agentes dados de documentos, arquivos e URLs via busca semântica (RAG). Knowledge dá aos agentes *o que saber*. + + + +--- + +## A Distinção Fundamental + +O mais importante a entender: **essas capacidades se dividem em duas categorias**. + +### Capacidades de Ação (Ferramentas, MCPs, Apps) + +Estas dão aos agentes a capacidade de **fazer coisas** — chamar APIs, ler arquivos, buscar na web, enviar emails. No momento da execução, os três tipos se resolvem no mesmo formato interno (instâncias de `BaseTool`) e aparecem em uma lista unificada de ferramentas que o agente pode chamar. + +```python +from crewai import Agent +from crewai_tools import SerperDevTool, FileReadTool + +agent = Agent( + role="Researcher", + goal="Find and compile market data", + backstory="Expert market analyst", + tools=[SerperDevTool(), FileReadTool()], # Ferramentas locais + mcps=["https://mcp.example.com/sse"], # Ferramentas de servidor MCP remoto + apps=["gmail", "google_sheets"], # Integrações com plataformas +) +``` + +### Capacidades de Contexto (Skills, Knowledge) + +Estas modificam o **prompt** do agente — injetando expertise, instruções ou dados recuperados antes do agente começar a raciocinar. Não dão aos agentes novas ações; elas moldam como os agentes pensam e a quais informações têm acesso. + +```python +from crewai import Agent + +agent = Agent( + role="Security Auditor", + goal="Audit cloud infrastructure for vulnerabilities", + backstory="Expert in cloud security with 10 years of experience", + skills=["./skills/security-audit"], # Instruções de domínio + knowledge_sources=[pdf_source, url_source], # Fatos recuperados +) +``` + +--- + +## Quando Usar o Quê + +| Você precisa... | Use | Exemplo | +| :------------------------------------------------------- | :---------------- | :--------------------------------------- | +| Agente buscar na web | **Ferramentas** | `tools=[SerperDevTool()]` | +| Agente chamar uma API remota via MCP | **MCPs** | `mcps=["https://api.example.com/sse"]` | +| Agente enviar emails pelo Gmail | **Apps** | `apps=["gmail"]` | +| Agente seguir procedimentos específicos | **Skills** | `skills=["./skills/code-review"]` | +| Agente consultar documentos da empresa | **Knowledge** | `knowledge_sources=[pdf_source]` | +| Agente buscar na web E seguir diretrizes de revisão | **Ferramentas + Skills** | Use ambos juntos | + +--- + +## Combinando Capacidades + +Na prática, agentes frequentemente usam **múltiplos tipos de capacidades juntos**. Aqui está um exemplo realista: + +```python +from crewai import Agent +from crewai_tools import SerperDevTool, FileReadTool, CodeInterpreterTool + +# Um agente de pesquisa totalmente equipado +researcher = Agent( + role="Senior Research Analyst", + goal="Produce comprehensive market analysis reports", + backstory="Expert analyst with deep industry knowledge", + + # AÇÃO: O que o agente pode FAZER + tools=[ + SerperDevTool(), # Buscar na web + FileReadTool(), # Ler arquivos locais + CodeInterpreterTool(), # Executar código Python para análise + ], + mcps=["https://data-api.example.com/sse"], # Acessar API de dados remota + apps=["google_sheets"], # Escrever no Google Sheets + + # CONTEXTO: O que o agente SABE + skills=["./skills/research-methodology"], # Como conduzir pesquisas + knowledge_sources=[company_docs], # Dados específicos da empresa +) +``` + +--- + +## Tabela Comparativa + +| Característica | Ferramentas | MCPs | Apps | Skills | Knowledge | +| :--- | :---: | :---: | :---: | :---: | :---: | +| **Dá ações ao agente** | ✅ | ✅ | ✅ | ❌ | ❌ | +| **Modifica o prompt** | ❌ | ❌ | ❌ | ✅ | ✅ | +| **Requer código** | Sim | Apenas config | Apenas config | Apenas Markdown | Apenas config | +| **Executa localmente** | Sim | Depende | Não (API AMP) | N/A | Sim | +| **Precisa de chaves API** | Por ferramenta | Por servidor | OAuth via AMP | Não | Apenas embedder | +| **Definido no Agent** | `tools=[]` | `mcps=[]` | `apps=[]` | `skills=[]` | `knowledge_sources=[]` | +| **Definido no Crew** | ❌ | ❌ | ❌ | `skills=[]` | `knowledge_sources=[]` | + +--- + +## Aprofundamentos + +Pronto para aprender mais sobre cada tipo de capacidade? + + + + Crie ferramentas personalizadas, use o catálogo OSS com 75+ opções, configure cache e execução assíncrona. + + + Conecte-se a servidores MCP via stdio, SSE ou HTTP. Filtre ferramentas, configure autenticação. + + + Construa pacotes de skills com SKILL.md, injete expertise de domínio, use divulgação progressiva. + + + Adicione conhecimento de PDFs, CSVs, URLs e mais. Configure embedders e recuperação. + + diff --git a/docs/pt-BR/concepts/skills.mdx b/docs/pt-BR/concepts/skills.mdx index 1af37f9e2..0f530390f 100644 --- a/docs/pt-BR/concepts/skills.mdx +++ b/docs/pt-BR/concepts/skills.mdx @@ -1,27 +1,186 @@ --- title: Skills -description: Pacotes de skills baseados em sistema de arquivos que injetam contexto nos prompts dos agentes. +description: Pacotes de skills baseados em sistema de arquivos que injetam expertise de domínio e instruções nos prompts dos agentes. icon: bolt mode: "wide" --- ## Visão Geral -Skills são diretórios autocontidos que fornecem aos agentes instruções, referências e assets específicos de domínio. Cada skill é definida por um arquivo `SKILL.md` com frontmatter YAML e um corpo em markdown. +Skills são diretórios autocontidos que fornecem aos agentes **instruções, diretrizes e material de referência específicos de domínio**. Cada skill é definida por um arquivo `SKILL.md` com frontmatter YAML e um corpo em markdown. -Skills usam **divulgação progressiva** — metadados são carregados primeiro, instruções completas apenas quando ativadas, e catálogos de recursos apenas quando necessário. +Quando ativada, as instruções de uma skill são injetadas diretamente no prompt da tarefa do agente — dando ao agente expertise sem exigir alterações de código. -## Estrutura de Diretório + +**Skills NÃO são ferramentas.** Este é o ponto de confusão mais comum. + +- **Skills** injetam *instruções e contexto* no prompt do agente. Elas dizem ao agente *como pensar* sobre um problema. +- **Ferramentas** dão ao agente *funções chamáveis* para tomar ações (buscar, ler arquivos, chamar APIs). + +Frequentemente você precisa de **ambos**: skills para expertise, ferramentas para ação. Eles são configurados independentemente e se complementam. + + +--- + +## Início Rápido + +### 1. Crie um Diretório de Skill ``` -my-skill/ -├── SKILL.md # Obrigatório — frontmatter + instruções -├── scripts/ # Opcional — scripts executáveis -├── references/ # Opcional — documentos de referência -└── assets/ # Opcional — arquivos estáticos (configs, dados) +skills/ +└── code-review/ + ├── SKILL.md # Obrigatório — instruções + ├── references/ # Opcional — documentos de referência + │ └── style-guide.md + └── scripts/ # Opcional — scripts executáveis ``` -O nome do diretório deve corresponder ao campo `name` no `SKILL.md`. +### 2. Escreva seu SKILL.md + +```markdown +--- +name: code-review +description: Guidelines for conducting thorough code reviews with focus on security and performance. +metadata: + author: your-team + version: "1.0" +--- + +## Diretrizes de Code Review + +Ao revisar código, siga esta checklist: + +1. **Segurança**: Verifique vulnerabilidades de injeção, bypasses de autenticação e exposição de dados +2. **Performance**: Procure por queries N+1, alocações desnecessárias e chamadas bloqueantes +3. **Legibilidade**: Garanta nomenclatura clara, comentários apropriados e estilo consistente +4. **Testes**: Verifique cobertura adequada de testes para novas funcionalidades + +### Níveis de Severidade +- **Crítico**: Vulnerabilidades de segurança, riscos de perda de dados → bloquear merge +- **Major**: Problemas de performance, erros de lógica → solicitar alterações +- **Minor**: Questões de estilo, sugestões de nomenclatura → aprovar com comentários +``` + +### 3. Anexe a um Agente + +```python +from crewai import Agent +from crewai_tools import GithubSearchTool, FileReadTool + +reviewer = Agent( + role="Senior Code Reviewer", + goal="Review pull requests for quality and security issues", + backstory="Staff engineer with expertise in secure coding practices.", + skills=["./skills"], # Injeta diretrizes de revisão + tools=[GithubSearchTool(), FileReadTool()], # Permite ao agente ler código +) +``` + +O agente agora tem tanto **expertise** (da skill) quanto **capacidades** (das ferramentas). + +--- + +## Skills + Ferramentas: Trabalhando Juntos + +Aqui estão padrões comuns mostrando como skills e ferramentas se complementam: + +### Padrão 1: Apenas Skills (Expertise de Domínio, Sem Ações Necessárias) + +Use quando o agente precisa de instruções específicas mas não precisa chamar serviços externos: + +```python +agent = Agent( + role="Technical Writer", + goal="Write clear API documentation", + backstory="Expert technical writer", + skills=["./skills/api-docs-style"], # Diretrizes e templates de escrita + # Sem ferramentas necessárias — agente escreve baseado no contexto fornecido +) +``` + +### Padrão 2: Apenas Ferramentas (Ações, Sem Expertise Especial) + +Use quando o agente precisa tomar ações mas não precisa de instruções específicas de domínio: + +```python +from crewai_tools import SerperDevTool, ScrapeWebsiteTool + +agent = Agent( + role="Web Researcher", + goal="Find information about a topic", + backstory="Skilled at finding information online", + tools=[SerperDevTool(), ScrapeWebsiteTool()], # Pode buscar e extrair dados + # Sem skills necessárias — pesquisa geral não precisa de diretrizes especiais +) +``` + +### Padrão 3: Skills + Ferramentas (Expertise E Ações) + +O padrão mais comum no mundo real. A skill fornece *como* abordar o trabalho; ferramentas fornecem *o que* o agente pode fazer: + +```python +from crewai_tools import SerperDevTool, FileReadTool, CodeInterpreterTool + +analyst = Agent( + role="Security Analyst", + goal="Audit infrastructure for vulnerabilities", + backstory="Expert in cloud security and compliance", + skills=["./skills/security-audit"], # Metodologia e checklists de auditoria + tools=[ + SerperDevTool(), # Pesquisar vulnerabilidades conhecidas + FileReadTool(), # Ler arquivos de configuração + CodeInterpreterTool(), # Executar scripts de análise + ], +) +``` + +### Padrão 4: Skills + MCPs + +Skills funcionam junto com servidores MCP da mesma forma que com ferramentas: + +```python +agent = Agent( + role="Data Analyst", + goal="Analyze customer data and generate reports", + backstory="Expert data analyst with strong statistical background", + skills=["./skills/data-analysis"], # Metodologia de análise + mcps=["https://data-warehouse.example.com/sse"], # Acesso remoto a dados +) +``` + +### Padrão 5: Skills + Apps + +Skills podem guiar como um agente usa integrações de plataforma: + +```python +agent = Agent( + role="Customer Support Agent", + goal="Respond to customer inquiries professionally", + backstory="Experienced support representative", + skills=["./skills/support-playbook"], # Templates de resposta e regras de escalação + apps=["gmail", "zendesk"], # Pode enviar emails e atualizar tickets +) +``` + +--- + +## Skills no Nível do Crew + +Skills podem ser definidas no crew para aplicar a **todos os agentes**: + +```python +from crewai import Crew + +crew = Crew( + agents=[researcher, writer, reviewer], + tasks=[research_task, write_task, review_task], + skills=["./skills"], # Todos os agentes recebem essas skills +) +``` + +Skills no nível do agente têm prioridade — se a mesma skill é descoberta em ambos os níveis, a versão do agente é usada. + +--- ## Formato do SKILL.md @@ -34,7 +193,7 @@ compatibility: crewai>=0.1.0 # opcional metadata: # opcional author: your-name version: "1.0" -allowed-tools: web-search file-read # opcional, delimitado por espaços +allowed-tools: web-search file-read # opcional, experimental --- Instruções para o agente vão aqui. Este corpo em markdown é injetado @@ -43,57 +202,46 @@ no prompt do agente quando a skill é ativada. ### Campos do Frontmatter -| Campo | Obrigatório | Restrições | +| Campo | Obrigatório | Descrição | | :-------------- | :---------- | :----------------------------------------------------------------------- | -| `name` | Sim | 1–64 chars. Alfanumérico minúsculo e hifens. Sem hifens iniciais/finais/consecutivos. Deve corresponder ao nome do diretório. | +| `name` | Sim | 1–64 chars. Alfanumérico minúsculo e hifens. Deve corresponder ao nome do diretório. | | `description` | Sim | 1–1024 chars. Descreve o que a skill faz e quando usá-la. | | `license` | Não | Nome da licença ou referência a um arquivo de licença incluído. | | `compatibility` | Não | Máx 500 chars. Requisitos de ambiente (produtos, pacotes, rede). | | `metadata` | Não | Mapeamento arbitrário de chave-valor string. | | `allowed-tools` | Não | Lista de ferramentas pré-aprovadas delimitada por espaços. Experimental. | -## Uso +--- -### Skills no Nível do Agente +## Estrutura de Diretório -Passe caminhos de diretório de skills para um agente: - -```python -from crewai import Agent - -agent = Agent( - role="Researcher", - goal="Find relevant information", - backstory="An expert researcher.", - skills=["./skills"], # descobre todas as skills neste diretório -) +``` +my-skill/ +├── SKILL.md # Obrigatório — frontmatter + instruções +├── scripts/ # Opcional — scripts executáveis +├── references/ # Opcional — documentos de referência +└── assets/ # Opcional — arquivos estáticos (configs, dados) ``` -### Skills no Nível do Crew +O nome do diretório deve corresponder ao campo `name` no `SKILL.md`. Os diretórios `scripts/`, `references/` e `assets/` estão disponíveis no `path` da skill para agentes que precisam referenciar arquivos diretamente. -Caminhos de skills no crew são mesclados em todos os agentes: +--- -```python -from crewai import Crew +## Skills Pré-carregadas -crew = Crew( - agents=[agent], - tasks=[task], - skills=["./skills"], -) -``` - -### Skills Pré-carregadas - -Você também pode passar objetos `Skill` diretamente: +Para mais controle, você pode descobrir e ativar skills programaticamente: ```python from pathlib import Path from crewai.skills import discover_skills, activate_skill +# Descobrir todas as skills em um diretório skills = discover_skills(Path("./skills")) + +# Ativá-las (carrega o corpo completo do SKILL.md) activated = [activate_skill(s) for s in skills] +# Passar para um agente agent = Agent( role="Researcher", goal="Find relevant information", @@ -102,13 +250,57 @@ agent = Agent( ) ``` +--- + ## Como as Skills São Carregadas -Skills carregam progressivamente — apenas os dados necessários em cada etapa são lidos: +Skills usam **divulgação progressiva** — carregando apenas o necessário em cada estágio: -| Etapa | O que é carregado | Quando | -| :--------------- | :------------------------------------------------ | :------------------ | -| Descoberta | Nome, descrição, campos do frontmatter | `discover_skills()` | -| Ativação | Texto completo do corpo do SKILL.md | `activate_skill()` | +| Estágio | O que é carregado | Quando | +| :--------- | :------------------------------------ | :------------------ | +| Descoberta | Nome, descrição, campos do frontmatter | `discover_skills()` | +| Ativação | Texto completo do corpo do SKILL.md | `activate_skill()` | -Durante a execução normal do agente, skills são automaticamente descobertas e ativadas. Os diretórios `scripts/`, `references/` e `assets/` estão disponíveis no `path` da skill para agentes que precisam referenciar arquivos diretamente. +Durante a execução normal do agente (passando caminhos de diretório via `skills=["./skills"]`), skills são automaticamente descobertas e ativadas. O carregamento progressivo só importa quando usando a API programática. + +--- + +## Skills vs Knowledge + +Tanto skills quanto knowledge modificam o prompt do agente, mas servem propósitos diferentes: + +| Aspecto | Skills | Knowledge | +| :--- | :--- | :--- | +| **O que fornece** | Instruções, procedimentos, diretrizes | Fatos, dados, informações | +| **Como é armazenado** | Arquivos Markdown (SKILL.md) | Embarcado em banco vetorial (ChromaDB) | +| **Como é recuperado** | Corpo inteiro injetado no prompt | Busca semântica encontra trechos relevantes | +| **Melhor para** | Metodologia, checklists, guias de estilo | Documentos da empresa, info de produto, dados de referência | +| **Definido via** | `skills=["./skills"]` | `knowledge_sources=[source]` | + +**Regra prática:** Se o agente precisa seguir um *processo*, use uma skill. Se o agente precisa consultar *dados*, use knowledge. + +--- + +## Perguntas Frequentes + + + + Depende do seu caso de uso. Skills e ferramentas são **independentes** — você pode usar qualquer um, ambos ou nenhum. + + - **Apenas skills**: Quando o agente precisa de expertise mas não de ações externas (ex: escrever com diretrizes de estilo) + - **Apenas ferramentas**: Quando o agente precisa de ações mas não de metodologia especial (ex: busca simples na web) + - **Ambos**: Quando o agente precisa de expertise E ações (ex: auditoria de segurança com checklists específicas E capacidade de escanear código) + + + + **Não.** O campo `allowed-tools` no SKILL.md é apenas metadado experimental — ele não provisiona nem injeta nenhuma ferramenta. Você deve sempre definir ferramentas separadamente via `tools=[]`, `mcps=[]` ou `apps=[]`. + + + + A skill no nível do agente tem prioridade. Skills são deduplicadas por nome — as skills do agente são processadas primeiro, então se o mesmo nome de skill aparece em ambos os níveis, a versão do agente é usada. + + + + Há um aviso suave em 50.000 caracteres, mas sem limite rígido. Mantenha skills focadas e concisas para melhores resultados — injeções de prompt muito grandes podem diluir a atenção do agente. + + diff --git a/docs/pt-BR/concepts/tools.mdx b/docs/pt-BR/concepts/tools.mdx index 21b1afed3..88479e017 100644 --- a/docs/pt-BR/concepts/tools.mdx +++ b/docs/pt-BR/concepts/tools.mdx @@ -10,6 +10,10 @@ mode: "wide" As ferramentas do CrewAI capacitam agentes com habilidades que vão desde busca na web e análise de dados até colaboração e delegação de tarefas entre colegas de trabalho. Esta documentação descreve como criar, integrar e aproveitar essas ferramentas dentro do framework CrewAI, incluindo um novo foco em ferramentas de colaboração. + + Ferramentas dão aos agentes **funções chamáveis** para tomar ações. Elas funcionam junto com [MCPs](/pt-BR/mcp/overview) (servidores de ferramentas remotos), [Apps](/pt-BR/concepts/agent-capabilities) (integrações com plataformas), [Skills](/pt-BR/concepts/skills) (expertise de domínio) e [Knowledge](/pt-BR/concepts/knowledge) (fatos recuperados). Veja a visão geral de [Capacidades do Agente](/pt-BR/concepts/agent-capabilities) para entender quando usar cada um. + + ## O que é uma Ferramenta? Uma ferramenta no CrewAI é uma habilidade ou função que os agentes podem utilizar para executar diversas ações.