---
title: "View source for AI Services/Agents - DreamFactory Wiki"
source: "https://wiki.dreamfactory.com/index.php?action=edit&title=AI_Services%2FAgents"
canonical_url: "https://wiki.dreamfactory.com/index.php?action=edit&title=AI_Services%2FAgents"
converted_at: "2026-11-22T15:06:18.820Z"
format: "markdown"
converted_by: "html-to-md-ai"
---
[]()
	
	
	
	# View source for AI Services/Agents

	
		
		← [AI Services/Agents](/AI_Services/Agents)
		
		
		
		[Jump to navigation](#mw-head)
		[Jump to search](#searchInput)
		You do not have permission to edit this page, for the following reason:

The action you have requested is limited to users in the group: [Users](/index.php?title=DreamFactory_Wiki:Users&action=edit&redlink=1).---

You can view and copy the source of this page.

{{#seo:
|title=Agents - DreamFactory Documentation
|title_mode=replace
|description=Register AI agents in DreamFactory with their own identity, role-scoped API key, and skills, and route tasks to the right agent with a deterministic capability router
|keywords=AI agents, agent identity, capability router, agent registry, RBAC, API key, skills
|og:title=Agents
|og:type=article
|og:site_name=DreamFactory Documentation
|og:description=Register AI agents in DreamFactory with their own identity, role-scoped API key, and skills, and route tasks to the right agent with a deterministic capability router
}}
'''Register AI agents in DreamFactory with their own identity, role-scoped API key, and skills, and route tasks to the right agent with a deterministic capability router'''

&lt;span id="agents">&lt;/span>
= Agents =

The '''Agents''' service gives every AI agent its own identity inside DreamFactory: a named record, a role that scopes what it may reach, its own API key with an optional lifetime, and a list of skills. Because an agent is a first-class record rather than a shared key, you can see which agent did what, revoke one without disturbing the others, and route work to the right agent programmatically.

Create the service from '''API Generation &amp;amp; Connections''' by adding a service of type '''Agents'''. It exposes three resources:

{| class="wikitable"
|-
! Resource
! Purpose
|-
| &lt;code>/api/v2/agents/agents&lt;/code>
| The agent registry — create, read, update, delete agents
|-
| &lt;code>/api/v2/agents/requests&lt;/code>
| The pending access-request queue
|-
| &lt;code>/api/v2/agents/route&lt;/code>
| Deterministic capability router (POST only)
|}

-----

&lt;span id="registering-an-agent">&lt;/span>
== Registering an agent ==

An agent record carries:

{| class="wikitable"
|-
! Field
! Description
|-
| &lt;code>name&lt;/code>
| The agent's name. Also scored by the router.
|-
| &lt;code>description&lt;/code>
| Free-text description. Also scored by the router.
|-
| &lt;code>role_id&lt;/code>
| The role that scopes what this agent may reach.
|-
| &lt;code>owner_id&lt;/code>
| The user who owns the agent.
|-
| &lt;code>api_key&lt;/code>
| The agent's own API key.
|-
| &lt;code>key_ttl_hours&lt;/code>
| Optional lifetime for the key, in hours.
|-
| &lt;code>skills&lt;/code>
| JSON array of capability keywords, for example &lt;code>[&amp;quot;invoice reconciliation&amp;quot;, &amp;quot;refunds&amp;quot;]&lt;/code>.
|-
| &lt;code>chat_service_id&lt;/code>
| Optional AI chat service to use as this agent's persona.
|-
| &lt;code>is_active&lt;/code>
| Only active agents are considered by the router.
|}

Scope each agent with a role exactly as you would an application. See [[Security/Role_Based_Access|Role-Based Access Control]].

-----

&lt;span id="approving-access-requests">&lt;/span>
== Approving access requests ==

Requests queue under &lt;code>/api/v2/agents/requests&lt;/code>. Approving or denying one is a &lt;code>PATCH&lt;/code> that sets the status — the model applies the side effects, including the resolution stamp, key rotation on approval, and the alert:

&lt;syntaxhighlight lang="bash">curl -X PATCH \
  "https://{instance}/api/v2/agents/requests/{id}" \
  -H "X-DreamFactory-API-Key: {api_key}" \
  -H "Content-Type: application/json" \
  -d '{"status": "approved"}'&lt;/syntaxhighlight>
Use &lt;code>&amp;quot;denied&amp;quot;&lt;/code> to reject. The admin UI's one-click approve is this same call.

-----

&lt;span id="routing-a-task-to-an-agent">&lt;/span>
== Routing a task to an agent ==

&lt;code>POST /api/v2/agents/route&lt;/code> answers "which registered agent should handle this?" without calling a model. The scoring is pure and deterministic: the same task and the same registry always produce the same answer.

&lt;syntaxhighlight lang="bash">curl -X POST \
  "https://{instance}/api/v2/agents/route" \
  -H "X-DreamFactory-API-Key: {api_key}" \
  -H "Content-Type: application/json" \
  -d '{"task": "reconcile last month'\''s invoices", "top": 3}'&lt;/syntaxhighlight>
{| class="wikitable"
|-
! Field
! Description
|-
| &lt;code>task&lt;/code>
| '''Required.''' Free-form description of the work.
|-
| &lt;code>top&lt;/code>
| How many scored agents to return. Defaults to &lt;code>3&lt;/code>, clamped to &lt;code>1&lt;/code>–&lt;code>25&lt;/code>.
|}

A match returns the winner, its chat persona service if one is configured, a human-readable reason, and the leaderboard:

&lt;syntaxhighlight lang="json">{
  "routed_to": { "id": 4, "name": "Finance Bot" },
  "chat_service_id": 12,
  "chat_service": "finance_chat",
  "reason": "matched: skill:invoice reconciliation",
  "scores": [
    { "id": 4, "name": "Finance Bot", "score": 4 },
    { "id": 7, "name": "Support Bot", "score": 1 }
  ]
}&lt;/syntaxhighlight>
When nothing scores above zero, &lt;code>routed_to&lt;/code> and the chat fields are &lt;code>null&lt;/code> and &lt;code>reason&lt;/code> is &lt;code>no registered agent matches&lt;/code> — the caller decides what to do next.

&lt;span id="how-scoring-works">&lt;/span>
=== How scoring works ===

Only active agents are considered. The task, each skill keyword, and each agent's name plus description are tokenized the same way: lowercased, split on runs of non-alphanumeric characters, tokens shorter than three characters dropped, then de-duplicated. Then:

* '''+3''' for each skill keyword whose tokens ''all'' appear in the task, so a multi-word skill like &lt;code>invoice reconciliation&lt;/code> counts once as a single hit rather than twice as two words
* '''+1''' for each name or description token found in the task, skipping any token already counted as part of a matched skill, so nothing is double-counted

Results are sorted by score, ties broken by lowest id. The practical consequence: '''skills drive routing''', and name and description only break ties. If an agent is being picked for the wrong work, edit its skills first.

{{Note|title=The router returns a decision, never a credential|The response contains an agent id, name, and chat service. It never returns &lt;code>api_key&lt;/code> or any other credential material — the routing call is safe to expose to a client that is not itself trusted with agent keys. &lt;code>GET&lt;/code> is not supported on this resource; routing is a computed action, so it is &lt;code>POST&lt;/code> only.}}

-----

&lt;span id="next-steps">&lt;/span>
== Next steps ==

* '''[[Security/Role_Based_Access|Role-Based Access Control]]''': Scope what an agent may reach
* '''[[AI_Services/AI_Chat|AI Chat]]''': Configure the chat service an agent uses as its persona
* '''[[AI_Services/Mcp_Service|MCP Server]]''': Expose your APIs to agents as tools

[[Category:Ai_Agents]]
[[Category:Agent_Identity]]
[[Category:Capability_Router]]
[[Category:Difficulty_Intermediate]]
Template used on this page:

- [Template:Note](/Template:Note) ([view source](/index.php?title=Template:Note&action=edit))

Return to [AI Services/Agents](/AI_Services/Agents).

Retrieved from "[https://wiki.dreamfactory.com/AI_Services/Agents](https://wiki.dreamfactory.com/AI_Services/Agents)"