Agent Tools

In DYPAI, tools are endpoints. Any endpoint you've already built — a SQL query, a workflow that charges a card, a function that sends an email — can be flipped on as a tool. The agent reads its description, decides when to call it, and gets back whatever the endpoint returns.

This means you don't write "agent tools" separately from your app. The same list_products endpoint that your React frontend calls via useEndpoint() can be called by the agent on behalf of a conversation.

Turning an endpoint into a tool

Authoring via YAML / MCP

When you (or your AI assistant) define an agent in YAML or through the MCP, you reference tools by their endpoint name, not by UUID:

agent:
  provider: DYPAI Managed
  model: gpt-5-nano
  tools: [list_tasks, create_task]

The codec maps those names to the underlying tool_ids (UUIDs) automatically, and maps them back to names when it reads the workflow. Don't hand-write tool_ids with names in them — list the endpoint names under tools and let DYPAI resolve the IDs.

Input schemas

The input schema tells the LLM what arguments it can pass. DYPAI uses standard JSON Schema.

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Search term for the product name"
    },
    "category": {
      "type": "string",
      "enum": ["electronics", "clothing", "books"],
      "description": "Optional category filter"
    },
    "max_price": {
      "type": "number",
      "description": "Maximum price in EUR"
    }
  },
  "required": ["query"]
}

Tips for good schemas:

• Use description on every field. The LLM reads these.
• Use enum to constrain choices when there's a fixed list — the LLM won't hallucinate values.
• Mark required fields so the LLM knows what it must provide.
• Keep it simple. A schema with 20 optional fields is usually a sign the tool should be split into two.

How the agent uses a tool

When the agent decides to call a tool:

1. The LLM generates the arguments matching the input schema.
2. DYPAI invokes the tool workflow inside the same project with the agent caller's user context. It does not make a new HTTP request or reapply the tool endpoint's HTTP auth and role settings.
3. The endpoint returns its normal response.
4. That response is fed back to the LLM as a tool result.
5. The agent decides whether to call another tool, or produce the final answer.

This all happens inside a single execution. Your frontend sees one streaming response, not five separate requests.

Guardrails

Agents can do a lot of damage if they loop forever or call tools without limits. DYPAI has several guardrails built in, configurable per agent:

Auth inside tools

Require JWT auth on the agent endpoint when tools need a verified user identity, and restrict its allowed roles when appropriate. Tools inherit that caller context: ${current_user_id} in SQL resolves to the caller's ID. However, a tool call executes the selected endpoint's workflow directly. The tool endpoint's HTTP auth mode and allowed roles are not checked again on this internal path, and DYPAI has no database row-level security (RLS).

Each tool workflow must check the caller's role and filter reads and writes to permitted records. A GET /my-orders endpoint can serve both your frontend and your agent, but JWT protection on its HTTP route alone does not make it safe as a tool. Put those checks inside the workflow so they apply to both paths.

What endpoints make good tools?

Limits

Next steps