i18n - docs translations (#23917)
Created by Github action Co-authored-by: github-actions <github-actions@twenty.com>
This commit is contained in:
github-actions[bot]
committed by
GitHub
GitHub
parent
72e6710545
commit
ff6e5847ab
@@ -152,5 +152,30 @@ export default defineApplicationRole({
|
||||
**تجنب الحلقات:** إذا استدعيت `runAgent()` من مشغل حدث قاعدة بيانات من نوع `*.updated` وقام الوكيل بتحديث نفس السجل، فحدد نطاق المشغل باستخدام `updatedFields` إلى حقل لا يكتبه الوكيل أبدًا (مثل عنوان URL المصدر)، أو تحقَّق مما إذا كان أي حقل مستهدف لا يزال فارغًا قبل استدعاء `runAgent()`.
|
||||
</Warning>
|
||||
|
||||
### التشغيل نيابةً عن أحد أعضاء مساحة العمل
|
||||
|
||||
مرر `runAsWorkspaceMemberId` عندما يتم تشغيل التنفيذ بواسطة شخص — مثل روبوت دردشة يجيب على رسالة، مثلاً — لكي يتصرف الوكيل بصفة ذلك العضو بدلًا من التطبيق:
|
||||
|
||||
```ts src/logic-functions/answer-question.ts
|
||||
const { result } = await runAgent({
|
||||
agentUniversalIdentifier: 'b3c4d5e6-f7a8-9012-bcde-f34567890123',
|
||||
prompt: 'How many open opportunities do we have?',
|
||||
runAsWorkspaceMemberId: '20202020-0687-4c41-b707-ed1bfca972a7',
|
||||
});
|
||||
```
|
||||
|
||||
يُقيَّد التنفيذ عندئذٍ بما تسمح به كلٌّ من دور الوكيل ودور العضو، وتُنسب السجلات التي ينشئها إلى ذلك العضو، وتُطبَّق أذونات العضو على مستوى الصف. احذف الحقل في عمليات التنفيذ الذاتية (المهام المجدولة، مشغلات أحداث قاعدة البيانات): في هذه الحالة يحتفظ الوكيل بدوره الخاص.
|
||||
|
||||
تطبيقك مسؤول عن تعيين الشخص الذي شغّل التنفيذ إلى عضو في مساحة العمل. يتطلب تسمية عضو ما رمز وصول للتطبيق، وما يمكن للرمز تسميته يعتمد على ما إذا كان يتضمن مستخدمًا أم لا:
|
||||
|
||||
* يمكن لرمز **بدون مستخدم مرفق** أن يسمّي أي عضو. تعمل الدالة المنطقية بدون مستخدم، وكذلك الرموز المُنشأة عبر `client_credentials` أو من مفتاح API.
|
||||
* لا يمكن لرمز مُصدَر **نيابةً عن مستخدم**، كما يستقبله مكوّن الواجهة الأمامية، أن يسمّي إلا العضو الخاص بذلك المستخدم فقط.
|
||||
|
||||
لا يمكن لأي شيء آخر — جلسة مستخدم عادية، أو مفتاح API بدون رمز تطبيق — أن يسمّي عضوًا على الإطلاق.
|
||||
|
||||
<Warning>
|
||||
يقوم `runAgent()` بإطلاق استثناء عندما يتعذّر حل عضو مساحة العمل — مثل عضو غير معروف أو تمت إزالته، أو ليس لديه أي دور. لا يعود إطلاقًا إلى دور الوكيل نفسه، لأن ذلك سيمنح صلاحيات وصول أكثر مما طلبه المستدعي.
|
||||
</Warning>
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
@@ -151,5 +151,37 @@ export default defineApplicationRole({
|
||||
**Vyhněte se smyčkám:** pokud voláte `runAgent()` z databázového triggeru `*.updated` a agent aktualizuje stejný záznam, omezte trigger pomocí `updatedFields` na pole, do kterého agent nikdy nezapisuje (např. zdrojovou URL), nebo před voláním `runAgent()` zkontrolujte, zda je některé cílové pole stále prázdné.
|
||||
</Warning>
|
||||
|
||||
### Spuštění jménem člena pracovního prostoru
|
||||
|
||||
Předejte `runAsWorkspaceMemberId`, když je spuštění vyvoláno osobou — například chatbotem odpovídajícím na zprávu — aby agent jednal jako tento člen, nikoli jako aplikace:
|
||||
|
||||
```ts src/logic-functions/answer-question.ts
|
||||
const { result } = await runAgent({
|
||||
agentUniversalIdentifier: 'b3c4d5e6-f7a8-9012-bcde-f34567890123',
|
||||
prompt: 'How many open opportunities do we have?',
|
||||
runAsWorkspaceMemberId: '20202020-0687-4c41-b707-ed1bfca972a7',
|
||||
});
|
||||
```
|
||||
|
||||
Spuštění je pak omezeno na to, co povolují jak role agenta, tak role člena, záznamy, které vytvoří, jsou připsány tomuto členovi a uplatní se jeho oprávnění na úrovni řádků. Toto pole vynechejte u autonomních spuštění (plánované úlohy, spouštěče databázových událostí): ta si ponechají vlastní roli agenta.
|
||||
|
||||
Vaše aplikace je zodpovědná za mapování osoby, která spuštění vyvolala, na člena pracovního prostoru. Pojmenování jednoho vyžaduje přístupový token aplikace a to, co může token
|
||||
pojmenovat, závisí na tom, zda nese uživatele:
|
||||
|
||||
* Token, který **nemá přiřazeného žádného uživatele**, může pojmenovat libovolného člena. Logická funkce běží
|
||||
s jedním a totéž platí pro tokeny získané přes `client_credentials` nebo z
|
||||
API klíče.
|
||||
* Token vydaný **jménem uživatele**, jaký obdrží front komponenta, smí
|
||||
pojmenovat pouze člena daného uživatele.
|
||||
|
||||
Cokoli jiného — běžná uživatelská relace, API klíč bez tokenu aplikace — vůbec
|
||||
nesmí pojmenovat žádného člena.
|
||||
|
||||
<Warning>
|
||||
`runAgent()` vyvolá výjimku, pokud nelze workspace člena vyřešit — neznámý nebo odebraný člen, nebo člen bez role. Nikdy se nevrací zpět k
|
||||
vlastní roli agenta, protože to by udělilo více oprávnění, než o která volající
|
||||
požádal.
|
||||
</Warning>
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
@@ -151,5 +151,37 @@ export default defineApplicationRole({
|
||||
**Vermeiden Sie Schleifen:** Wenn Sie `runAgent()` von einem `*.updated`-Datenbankereignis-Trigger aus aufrufen und der Agent denselben Datensatz aktualisiert, schränken Sie den Trigger mit `updatedFields` auf ein Feld ein, das der Agent niemals beschreibt (z. B. die Quell-URL), oder prüfen Sie, ob eines der Zielfelder noch leer ist, bevor Sie `runAgent()` aufrufen.
|
||||
</Warning>
|
||||
|
||||
### Ausführung im Namen eines Arbeitsbereichsmitglieds
|
||||
|
||||
Übergeben Sie `runAsWorkspaceMemberId`, wenn die Ausführung von einer Person ausgelöst wird – zum Beispiel von einem Chatbot, der auf eine Nachricht antwortet –, damit der Agent als dieses Mitglied und nicht als die App agiert:
|
||||
|
||||
```ts src/logic-functions/answer-question.ts
|
||||
const { result } = await runAgent({
|
||||
agentUniversalIdentifier: 'b3c4d5e6-f7a8-9012-bcde-f34567890123',
|
||||
prompt: 'How many open opportunities do we have?',
|
||||
runAsWorkspaceMemberId: '20202020-0687-4c41-b707-ed1bfca972a7',
|
||||
});
|
||||
```
|
||||
|
||||
Die Ausführung ist dann auf das beschränkt, was sowohl die Rolle des Agenten als auch die des Mitglieds erlauben; die dabei erstellten Datensätze werden diesem Mitglied zugeordnet, und die Berechtigungen auf Zeilenebene des Mitglieds gelten. Lassen Sie das Feld bei autonomen Ausführungen weg (geplante Jobs, Datenbankereignis-Trigger): Diese behalten die eigene Rolle des Agenten bei.
|
||||
|
||||
Ihre App ist dafür verantwortlich, die Person, die die Ausführung ausgelöst hat, einem Arbeitsbereichsmitglied zuzuordnen. Das Benennen eines Mitglieds erfordert ein App-Zugriffstoken, und was ein Token benennen darf, hängt davon ab, ob ihm ein Benutzer zugeordnet ist:
|
||||
|
||||
* Ein Token **ohne angehängten Benutzer** kann jedes Mitglied benennen. Eine Logikfunktion läuft
|
||||
mit einem solchen, und ebenso gilt dies für Token, die über `client_credentials` oder aus einem API-
|
||||
Schlüssel ausgestellt werden.
|
||||
* Ein Token, das **im Namen eines Benutzers** ausgestellt wird, wie es eine Frontkomponente erhält, darf
|
||||
nur das eigene Mitglied dieses Benutzers benennen.
|
||||
|
||||
Alles andere — eine einfache Benutzersitzung, ein API-Schlüssel ohne App-Token — darf
|
||||
überhaupt kein Mitglied benennen.
|
||||
|
||||
<Warning>
|
||||
`runAgent()` löst eine Ausnahme aus, wenn das Arbeitsbereichsmitglied nicht aufgelöst werden kann — ein
|
||||
unbekanntes oder entferntes Mitglied oder eines ohne Rolle. Es greift niemals auf die
|
||||
eigene Rolle des Agenten zurück, da dies mehr Zugriff gewähren würde, als der Aufrufer angefordert
|
||||
hat.
|
||||
</Warning>
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
@@ -152,5 +152,36 @@ export default defineApplicationRole({
|
||||
**Evita los bucles:** si llamas a `runAgent()` desde un trigger de evento de base de datos `*.updated` y el agente actualiza el mismo registro, limita el alcance del trigger con `updatedFields` a un campo que el agente nunca escriba (por ejemplo, la URL de origen), o comprueba si algún campo de destino sigue vacío antes de llamar a `runAgent()`.
|
||||
</Warning>
|
||||
|
||||
### Ejecución en nombre de un miembro del espacio de trabajo
|
||||
|
||||
Pasa `runAsWorkspaceMemberId` cuando la ejecución es activada por una persona — por ejemplo, un bot de chat que responde a un mensaje — para que el agente actúe como ese miembro en lugar de como la aplicación:
|
||||
|
||||
```ts src/logic-functions/answer-question.ts
|
||||
const { result } = await runAgent({
|
||||
agentUniversalIdentifier: 'b3c4d5e6-f7a8-9012-bcde-f34567890123',
|
||||
prompt: 'How many open opportunities do we have?',
|
||||
runAsWorkspaceMemberId: '20202020-0687-4c41-b707-ed1bfca972a7',
|
||||
});
|
||||
```
|
||||
|
||||
La ejecución queda entonces restringida a lo que **tanto** el rol del agente como el rol del miembro permiten, los registros que crea se atribuyen a ese miembro y se aplican los permisos a nivel de fila de ese miembro. Omite el campo para ejecuciones autónomas (trabajos programados, disparadores de eventos de base de datos): esos conservan el rol propio del agente.
|
||||
|
||||
Tu aplicación es responsable de asociar a la persona que activó la ejecución con un miembro del espacio de trabajo. Para poder designar uno se requiere un token de acceso de la aplicación, y a quién puede
|
||||
designar un token depende de si lleva asociado un usuario:
|
||||
|
||||
* Un token **sin usuario asociado** puede designar a cualquier miembro. Una función lógica se ejecuta
|
||||
con uno, y lo mismo ocurre con los tokens generados mediante `client_credentials` o a partir de una clave de API.
|
||||
* Un token emitido **en nombre de un usuario**, como el que recibe un componente de interfaz, solo puede
|
||||
designar al miembro propio de ese usuario.
|
||||
|
||||
Cualquier otro caso — una sesión de usuario simple, una clave de API sin un token de la aplicación — no puede
|
||||
designar a ningún miembro.
|
||||
|
||||
<Warning>
|
||||
`runAgent()` produce un error cuando no se puede resolver el miembro del espacio de trabajo — un
|
||||
miembro desconocido o eliminado, o uno sin rol. Nunca recurre al
|
||||
rol propio del agente, ya que eso otorgaría más acceso del que solicitó quien llama.
|
||||
</Warning>
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
@@ -154,5 +154,37 @@ export default defineApplicationRole({
|
||||
**Évitez les boucles :** si vous appelez `runAgent()` à partir d'un déclencheur d'événement de base de données `*.updated` et que l'agent met à jour le même enregistrement, limitez le déclencheur avec `updatedFields` à un champ que l'agent n'écrit jamais (par exemple l'URL source), ou vérifiez si un champ cible est encore vide avant d'appeler `runAgent()`.
|
||||
</Warning>
|
||||
|
||||
### Exécution au nom d’un membre de l’espace de travail
|
||||
|
||||
Passez `runAsWorkspaceMemberId` lorsque l’exécution est déclenchée par une personne — par exemple un chatbot répondant à un message — afin que l’agent agisse comme ce membre plutôt qu’en tant qu’application :
|
||||
|
||||
```ts src/logic-functions/answer-question.ts
|
||||
const { result } = await runAgent({
|
||||
agentUniversalIdentifier: 'b3c4d5e6-f7a8-9012-bcde-f34567890123',
|
||||
prompt: 'How many open opportunities do we have?',
|
||||
runAsWorkspaceMemberId: '20202020-0687-4c41-b707-ed1bfca972a7',
|
||||
});
|
||||
```
|
||||
|
||||
L’exécution est alors limitée à ce que les rôles de l’agent et du membre autorisent **tous deux**, les enregistrements qu’elle crée sont attribués à ce membre, et les autorisations au niveau des lignes du membre s’appliquent. Omettez ce champ pour les exécutions autonomes (tâches planifiées, déclencheurs d’événements de base de données) : celles-ci conservent le rôle propre de l’agent.
|
||||
|
||||
Votre application est responsable de faire correspondre la personne qui a déclenché l’exécution à un membre de l’espace de travail. Nommer un membre nécessite un jeton d’accès d’application, et ce qu’un jeton peut
|
||||
nommer dépend du fait qu’il transporte ou non un utilisateur :
|
||||
|
||||
* Un jeton **sans utilisateur associé** peut nommer n’importe quel membre. Une fonction logique s’exécute
|
||||
avec un tel jeton, tout comme les jetons créés via `client_credentials` ou à partir d’une clé
|
||||
d’API.
|
||||
* Un jeton émis **au nom d’un utilisateur**, comme en reçoit un composant frontal, ne peut
|
||||
nommer que le membre de cet utilisateur lui-même.
|
||||
|
||||
Tout autre type — une simple session utilisateur, une clé d’API sans jeton d’application — ne peut pas
|
||||
nommer de membre du tout.
|
||||
|
||||
<Warning>
|
||||
`runAgent()` lève une exception lorsque le membre de l’espace de travail ne peut pas être résolu — un
|
||||
membre inconnu ou supprimé, ou un membre sans rôle. Elle ne revient jamais au rôle
|
||||
propre de l’agent, car cela accorderait plus d’accès que ce que l’appelant a demandé.
|
||||
</Warning>
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
@@ -151,5 +151,32 @@ export default defineApplicationRole({
|
||||
**Evita i loop:** se chiami `runAgent()` da un trigger di evento del database `*.updated` e l'agente aggiorna lo stesso record, limita il trigger con `updatedFields` a un campo che l'agente non scrive mai (ad esempio l'URL di origine), oppure controlla che almeno uno dei campi di destinazione sia ancora vuoto prima di chiamare `runAgent()`.
|
||||
</Warning>
|
||||
|
||||
### Esecuzione per conto di un membro dello spazio di lavoro
|
||||
|
||||
Passa `runAsWorkspaceMemberId` quando l'esecuzione viene attivata da una persona — ad esempio un chatbot che risponde a un messaggio — in modo che l'agente agisca come quel membro invece che come l'app:
|
||||
|
||||
```ts src/logic-functions/answer-question.ts
|
||||
const { result } = await runAgent({
|
||||
agentUniversalIdentifier: 'b3c4d5e6-f7a8-9012-bcde-f34567890123',
|
||||
prompt: 'How many open opportunities do we have?',
|
||||
runAsWorkspaceMemberId: '20202020-0687-4c41-b707-ed1bfca972a7',
|
||||
});
|
||||
```
|
||||
|
||||
L'esecuzione è quindi limitata a ciò che sia il ruolo dell'agente sia quello del membro consentono; i record che crea sono attribuiti a quel membro e si applicano le autorizzazioni a livello di riga del membro. Ometti il campo per le esecuzioni autonome (attività pianificate, trigger di eventi del database): queste mantengono il ruolo proprio dell'agente.
|
||||
|
||||
La tua app è responsabile di mappare la persona che ha attivato l'esecuzione a un membro dello spazio di lavoro. Per specificarne uno è necessario un token di accesso dell'app e ciò che un token può specificare dipende dal fatto che sia o meno associato a un utente:
|
||||
|
||||
* Un token senza alcun utente associato può specificare qualsiasi membro. Una funzione logica viene eseguita con uno, e così anche i token generati tramite `client_credentials` o da una chiave API.
|
||||
* Un token emesso per conto di un utente, come quello che riceve un front component, può specificare solo il membro dell'utente stesso.
|
||||
|
||||
Qualsiasi altra cosa — una semplice sessione utente, una chiave API senza un token dell'app — non può specificare affatto un membro.
|
||||
|
||||
<Warning>
|
||||
`runAgent()` genera un errore quando il membro dello spazio di lavoro non può essere risolto — un
|
||||
membro sconosciuto o rimosso, o uno senza ruolo. Non ricorre mai al
|
||||
ruolo proprio dell'agente, poiché ciò concederebbe più accesso di quanto richiesto dal chiamante.
|
||||
</Warning>
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
@@ -150,5 +150,32 @@ export default defineApplicationRole({
|
||||
**ループを避けてください:** `*.updated` データベースイベントトリガーから `runAgent()` を呼び出し、そのエージェントが同じレコードを更新する場合、`updatedFields` を使ってエージェントが決して書き込まないフィールド（例: ソース URL）にスコープするか、`runAgent()` を呼び出す前に、対象フィールドのいずれかがまだ空であるかどうかを判定してガードしてください。
|
||||
</Warning>
|
||||
|
||||
### ワークスペースメンバーを代理して実行する場合
|
||||
|
||||
実行が人によってトリガーされた場合 — たとえばメッセージに返信するチャットボットなど — には、`runAsWorkspaceMemberId` を渡して、そのエージェントがアプリとしてではなく、そのメンバーとして動作するようにします。
|
||||
|
||||
```ts src/logic-functions/answer-question.ts
|
||||
const { result } = await runAgent({
|
||||
agentUniversalIdentifier: 'b3c4d5e6-f7a8-9012-bcde-f34567890123',
|
||||
prompt: 'How many open opportunities do we have?',
|
||||
runAsWorkspaceMemberId: '20202020-0687-4c41-b707-ed1bfca972a7',
|
||||
});
|
||||
```
|
||||
|
||||
その場合、実行はエージェントのロールとメンバーのロールの**両方**で許可されている範囲に制限され、作成されたレコードはそのメンバーに帰属し、メンバーの行レベル権限が適用されます。 自律的な実行（スケジュールされたジョブ、データベースイベントトリガー）の場合は、そのフィールドを省略します。この場合、エージェント自身のロールが維持されます。
|
||||
|
||||
実行をトリガーした人物を、どのワークスペースメンバーに対応付けるかは、あなたのアプリ側の責任です。 メンバーを指定するにはアプリアクセストークンが必要であり、トークンで指定できるメンバーは、そのトークンにユーザーが紐づいているかどうかに依存します。
|
||||
|
||||
* ユーザーが紐づいていないトークンは、任意のメンバーを指定できます。 ロジック関数はそのようなトークンで実行され、`client_credentials` を通じて、または API
|
||||
キーから発行されたトークンも同様です。
|
||||
* フロントコンポーネントが受け取るような、ユーザーを代表して発行されたトークンは、そのユーザー自身のメンバーのみを指定できます。
|
||||
|
||||
それ以外、つまり通常のユーザーセッションやアプリアクセストークンを伴わない API キーは、メンバーをまったく指定できません。
|
||||
|
||||
<Warning>
|
||||
`runAgent()` は、ワークスペースメンバーを解決できない場合（不明または削除されたメンバー、あるいはロールを持たないメンバー）に例外をスローします。 呼び出し元が要求した以上のアクセス権を与えてしまうことになるため、
|
||||
エージェント自身のロールにフォールバックすることは決してありません。
|
||||
</Warning>
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
@@ -150,5 +150,33 @@ export default defineApplicationRole({
|
||||
**루프를 피하세요:** `*.updated` 데이터베이스 이벤트 트리거에서 `runAgent()`를 호출하고 에이전트가 동일한 레코드를 업데이트하는 경우, `updatedFields`를 에이전트가 절대 쓰지 않는 필드(예: 원본 URL)로 한정하거나, `runAgent()`를 호출하기 전에 대상 필드 중 어느 것이든 아직 비어 있는지 여부를 검사해 가드하세요.
|
||||
</Warning>
|
||||
|
||||
### 워크스페이스 멤버를 대신해 실행하기
|
||||
|
||||
실행이 사람에 의해 트리거되는 경우(예: 메시지에 응답하는 챗봇) `runAsWorkspaceMemberId`를 전달하면, 에이전트가 앱이 아니라 해당 멤버로서 동작합니다:
|
||||
|
||||
```ts src/logic-functions/answer-question.ts
|
||||
const { result } = await runAgent({
|
||||
agentUniversalIdentifier: 'b3c4d5e6-f7a8-9012-bcde-f34567890123',
|
||||
prompt: 'How many open opportunities do we have?',
|
||||
runAsWorkspaceMemberId: '20202020-0687-4c41-b707-ed1bfca972a7',
|
||||
});
|
||||
```
|
||||
|
||||
그러면 실행은 에이전트의 역할과 멤버의 역할이 **모두** 허용하는 범위로 제한되고, 생성되는 레코드는 해당 멤버에게 귀속되며, 멤버의 행 단위(row-level) 권한이 적용됩니다. 자율 실행(예약된 작업, 데이터베이스 이벤트 트리거)에는 이 필드를 생략하세요. 이러한 실행은 에이전트의 고유 역할을 유지합니다.
|
||||
|
||||
실행을 트리거한 사람을 워크스페이스 멤버와 매핑하는 책임은 앱에 있습니다. 이름을 지정하려면 앱 액세스 토큰이 필요하며, 토큰이 어떤 멤버를
|
||||
지정할 수 있는지는 그 토큰에 사용자가 포함되어 있는지 여부에 따라 달라집니다:
|
||||
|
||||
* **사용자가 연결되지 않은** 토큰은 어떤 멤버든 이름을 지정할 수 있습니다. 하나를 사용해 로직 함수가 실행되며,
|
||||
`client_credentials`를 통해 발급된 토큰이나 API 키에서 발급된 토큰도 마찬가지입니다.
|
||||
* 프론트 컴포넌트가 받는 것처럼 **사용자를 대신해 발급된** 토큰은 해당 사용자의 멤버만 지정할 수 있습니다.
|
||||
|
||||
그 밖의 것들 — 일반 사용자 세션, 앱 토큰이 없는 API 키 — 은 멤버를 전혀 지정할 수 없습니다.
|
||||
|
||||
<Warning>
|
||||
`runAgent()`는 워크스페이스 멤버를 확인할 수 없을 때 — 알 수 없거나 제거되었거나, 역할이 없는 멤버인 경우 — 예외를 발생시킵니다. 호출자가 요청한 것보다 더 많은 액세스를 부여하게 되므로,
|
||||
에이전트 자신의 역할로는 절대 폴백하지 않습니다.
|
||||
</Warning>
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
@@ -153,5 +153,32 @@ export default defineApplicationRole({
|
||||
**Evită buclele:** dacă apelezi `runAgent()` dintr-un declanșator de tip eveniment de bază de date `*.updated`, iar agentul actualizează aceeași înregistrare, restrânge declanșatorul cu `updatedFields` la un câmp pe care agentul nu îl scrie niciodată (de exemplu, URL-ul sursă) sau verifică dacă vreun câmp țintă este încă gol înainte de a apela `runAgent()`.
|
||||
</Warning>
|
||||
|
||||
### Rulare în numele unui membru al spațiului de lucru
|
||||
|
||||
Transmite `runAsWorkspaceMemberId` atunci când rularea este declanșată de o persoană — de exemplu, un chatbot care răspunde la un mesaj — astfel încât agentul să acționeze ca acel membru în loc să acționeze ca aplicația:
|
||||
|
||||
```ts src/logic-functions/answer-question.ts
|
||||
const { result } = await runAgent({
|
||||
agentUniversalIdentifier: 'b3c4d5e6-f7a8-9012-bcde-f34567890123',
|
||||
prompt: 'How many open opportunities do we have?',
|
||||
runAsWorkspaceMemberId: '20202020-0687-4c41-b707-ed1bfca972a7',
|
||||
});
|
||||
```
|
||||
|
||||
Rularea este apoi limitată la ceea ce permit **atât** rolul agentului, cât și rolul membrului, înregistrările pe care le creează sunt atribuite acelui membru, iar permisiunile la nivel de rând ale membrului se aplică. Omite câmpul pentru rulările autonome (joburi programate, declanșatoare de evenimente din baza de date): acelea păstrează propriul rol al agentului.
|
||||
|
||||
Aplicația ta este responsabilă să facă asocierea dintre persoana care a declanșat rularea și un membru al spațiului de lucru. A denumi unul necesită un token de acces al aplicației, iar ceea ce poate denumi un token depinde dacă acesta are sau nu un utilizator asociat:
|
||||
|
||||
* Un token **fără niciun utilizator atașat** poate denumi orice membru. O funcție logică rulează cu unul, la fel și tokenurile emise prin `client_credentials` sau dintr-o cheie API.
|
||||
* Un token emis **în numele unui utilizator**, așa cum primește un front component, poate
|
||||
denumi doar propriul membru al acelui utilizator.
|
||||
|
||||
Orice altceva — o sesiune simplă de utilizator, o cheie API fără un token al aplicației — nu poate denumi deloc un membru.
|
||||
|
||||
<Warning>
|
||||
`runAgent()` aruncă o eroare atunci când membrul spațiului de lucru nu poate fi identificat — un membru necunoscut sau eliminat, ori unul fără niciun rol. Nu revine niciodată la
|
||||
propriul rol al agentului, deoarece acest lucru ar acorda mai mult acces decât a cerut apelantul.
|
||||
</Warning>
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
@@ -150,5 +150,36 @@ export default defineApplicationRole({
|
||||
**Döngülerden kaçının:** Bir `*.updated` veritabanı olayı tetikleyicisinden `runAgent()` çağırırsanız ve ajan aynı kaydı güncelliyorsa, tetikleyiciyi, ajan tarafından asla yazılmayan bir alana (örneğin kaynak URL) göre `updatedFields` ile kapsamlandırın veya `runAgent()` çağırmadan önce herhangi bir hedef alanın hâlâ boş olup olmadığına göre koruma ekleyin.
|
||||
</Warning>
|
||||
|
||||
### Bir çalışma alanı üyesi adına çalıştırma
|
||||
|
||||
Çalıştırma bir kişi tarafından tetiklendiğinde — örneğin bir mesajı yanıtlayan bir sohbet
|
||||
botu — ajanın uygulama yerine o üye olarak davranması için `runAsWorkspaceMemberId` iletin:
|
||||
|
||||
```ts src/logic-functions/answer-question.ts
|
||||
const { result } = await runAgent({
|
||||
agentUniversalIdentifier: 'b3c4d5e6-f7a8-9012-bcde-f34567890123',
|
||||
prompt: 'How many open opportunities do we have?',
|
||||
runAsWorkspaceMemberId: '20202020-0687-4c41-b707-ed1bfca972a7',
|
||||
});
|
||||
```
|
||||
|
||||
Ardından çalıştırma, **hem** ajanın rolünün hem de üyenin rolünün izin verdiğiyle sınırlandırılır, oluşturduğu kayıtlar o üyeye atfedilir ve üyenin satır düzeyi izinleri uygulanır. Otonom çalıştırmalar (zamanlanmış işler, veritabanı olayı tetikleyicileri) için alanı atlayın: bunlar ajanın kendi rolünü korur.
|
||||
|
||||
Çalıştırmayı tetikleyen kişiyi bir çalışma alanı üyesiyle eşleştirmekten uygulamanız sorumludur. Birini belirtmek bir uygulama erişim belirteci gerektirir ve bir belirtecin neyi
|
||||
belirtebileceği, bir kullanıcı içerip içermediğine bağlıdır:
|
||||
|
||||
* **Kullanıcı ile ilişkili olmayan** bir belirteç herhangi bir üyeyi belirtebilir. Bir mantık fonksiyonu bunlardan biriyle çalışır ve `client_credentials` aracılığıyla ya da bir API
|
||||
anahtarından oluşturulan belirteçler de aynı şekilde çalışır.
|
||||
* Bir ön bileşenin aldığı gibi, **bir kullanıcının adına düzenlenmiş** bir belirteç yalnızca o kullanıcının kendi üyesini
|
||||
belirtebilir.
|
||||
|
||||
Bunların dışındaki her şey — sıradan bir kullanıcı oturumu, bir uygulama belirteci olmayan bir API anahtarı — hiçbir şekilde
|
||||
bir üyeyi belirtemez.
|
||||
|
||||
<Warning>
|
||||
`runAgent()` çalışma alanı üyesi çözülemediğinde — bilinmeyen veya kaldırılmış bir üye ya da rolü olmayan bir üye — hata fırlatır. Bu, çağıranın istediğinden daha fazla erişim sağlayacağından asla
|
||||
ajanın kendi rolüne geri dönmez.
|
||||
</Warning>
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
Reference in New Issue
Block a user