> For the complete documentation index, see [llms.txt](https://docs.amigo.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.amigo.ai/developer-guide/platform-api/functions.md).

# Platform Functions

Platform functions are workspace-registered computation tools for agent data access. You register a supported SQL query, Python function, AI composition, or table-valued function in the workspace function registry. Supported agent runtimes can expose a successfully loaded function during conversations; the function runs on the platform's compute layer without a separate application container.

Each function is identified by name within a workspace. Deploying the same name updates that function in place; the public REST API does not expose function versions, aliases, promote, or rollback operations.

{% hint style="info" %}
**Conceptual overview.** For background on named functions and how functions relate to Actions and Skills, see the [Platform Functions conceptual docs](https://docs.amigo.ai/agent/platform-functions#named-functions).
{% endhint %}

## Function Types

| Type (`function_type`) | Description                                                                           |
| ---------------------- | ------------------------------------------------------------------------------------- |
| `sql`                  | Parameterized SQL template returning rows or a scalar across live and analytical data |
| `ai`                   | SQL wrapping an AI query (classify, summarize, extract, mask)                         |
| `python`               | Warehouse-sandboxed scalar Python user-defined function                               |
| `udtf`                 | Warehouse-sandboxed table-valued user-defined function                                |

The `function_type` field is a closed set of these four values. A separate `returns_kind` field describes whether a function returns a `table` (rows as a list of objects) or a `scalar` (a single value); this is independent of the function type.

## Tools in the Agent's Context Graph

A platform function can surface as a tool after it is registered for the workspace and loaded by a supported runtime. Availability for a session also depends on the selected runtime and any applicable context-graph bindings. When exposed, the agent sees the function's tool name, description, input schema, and result.

### Named Functions

Named functions are registered computations with fixed input schemas. When loaded as agent tools, they use the `fn_` prefix (for example, `fn_caller_history` or `fn_entity_confidence`).

Depending on deployment and workspace registration, common examples can include entity confidence assessment, caller history, and patient summaries. Do not assume an example is available in a session without checking registration and runtime loading; see [Named Functions](https://docs.amigo.ai/agent/platform-functions#named-functions) for the conceptual model.

### Long-Tail and Ad Hoc Queries

For questions no named function anticipates, use [workspace data queries](/developer-guide/platform-api/functions/workspace-data-queries.md) (`wsq_<name>`): parameterized SQL templates registered per workspace and surfaced to the agent at session start.

Platform functions are read-only by construction (SELECT/WITH only; INSERT/UPDATE/DELETE are rejected). World model writes go through dedicated write tools, not through this surface.

### Loading and State Gating

Functions and workspace data queries are loaded at session start from the workspace's function store. In the standard HSM runtime, registered functions and queries with descriptions are exposed per context-graph state through `tool_call_specs`. Native and realtime runtimes can additionally attach a runtime-defined shared platform or system tool set globally, so absence from a state's spec is not a universal security guarantee. Platform functions remain read-only, and runtime authorization and write-scope checks remain the execution boundary.

```yaml
tool_call_specs:
  - tool_id: fn_entity_confidence
  - tool_id: wsq_caller_lookup
    additional_instruction: "Look up the caller's recent records when no existing tool fits"
```

## Built-in Tool Catalog

Returns the live catalog of built-in tools the platform exposes at runtime, so integrators and tooling can discover what is available rather than relying on a hardcoded list. The catalog stays current as built-in tools are added or retired. Read-only; requires a workspace API key.

{% openapi src="<https://api.platform.amigo.ai/v1/openapi.json>" path="/v1/{workspace\_id}/tools/catalog" method="get" %}
<https://api.platform.amigo.ai/v1/openapi.json>
{% endopenapi %}

This catalog covers the platform's built-in tools. Workspace-specific tools - deployed platform functions (`fn_*`, listed [below](#list-functions)) and [workspace data queries](/developer-guide/platform-api/functions/workspace-data-queries.md) (`wsq_*`) - are discovered through their own list endpoints.

## Deploy or Update a Function

Validates and upserts a function. The URL `function_name` is authoritative and must match the request body `name`.

{% openapi src="<https://api.platform.amigo.ai/v1/openapi.json>" path="/v1/{workspace\_id}/functions/{function\_name}" method="put" %}
<https://api.platform.amigo.ai/v1/openapi.json>
{% endopenapi %}

### Example

```bash
curl -X PUT "https://api.platform.amigo.ai/v1/$WORKSPACE_ID/functions/active_patients" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "active_patients",
    "description": "Returns active patients for a location.",
    "function_type": "sql",
    "returns": "table",
    "body": "SELECT id, name FROM patients WHERE location_id = :location_id",
    "parameters": [
      {
        "name": "location_id",
        "type": "string",
        "description": "Location identifier."
      }
    ]
  }'
```

**Permissions:** Admin or Owner role.

## List Functions

Returns the registered functions in the workspace.

{% openapi src="<https://api.platform.amigo.ai/v1/openapi.json>" path="/v1/{workspace\_id}/functions" method="get" %}
<https://api.platform.amigo.ai/v1/openapi.json>
{% endopenapi %}

## Get a Function

Returns a single registered function.

{% openapi src="<https://api.platform.amigo.ai/v1/openapi.json>" path="/v1/{workspace\_id}/functions/{function\_name}" method="get" %}
<https://api.platform.amigo.ai/v1/openapi.json>
{% endopenapi %}

## Invoke a Function

Executes a registered function with caller-supplied arguments.

{% openapi src="<https://api.platform.amigo.ai/v1/openapi.json>" path="/v1/{workspace\_id}/functions/{function\_name}/invoke" method="post" %}
<https://api.platform.amigo.ai/v1/openapi.json>
{% endopenapi %}

**Permissions:** Workspace view permission.

## Test a Function

Runs the same execution path as invoke and stores `last_test_*` telemetry on the function. Logical execution failures return `200` with `status: "fail"` and an `error` value so dashboards can render the failure detail.

{% openapi src="<https://api.platform.amigo.ai/v1/openapi.json>" path="/v1/{workspace\_id}/functions/{function\_name}/test" method="post" %}
<https://api.platform.amigo.ai/v1/openapi.json>
{% endopenapi %}

**Permissions:** Admin or Owner role.

## Delete a Function

Deletes a registered function. Deleting a Python or UDTF function also removes its warehouse artifact; if the artifact drop fails, the registry entry is preserved so the delete can be retried safely.

{% openapi src="<https://api.platform.amigo.ai/v1/openapi.json>" path="/v1/{workspace\_id}/functions/{function\_name}" method="delete" %}
<https://api.platform.amigo.ai/v1/openapi.json>
{% endopenapi %}

**Permissions:** Admin or Owner role.

## CLI

Platform functions can be managed through Agent Forge:

```
forge platform function list                          # List registered functions
forge platform function catalog                       # List callable catalog entries
forge platform function sync                          # Sync platform functions
forge platform function register --file function.json # Register or update a function
forge platform function test <name> --input '{}'      # Test a registered function
forge platform function query --sql 'SELECT 1'        # Run an ad hoc read-only query
forge platform function delete <name> --yes           # Remove a function
```

## Comparison with Data-MCP

Platform functions are the primitive for agent data access; [Data-MCP](/developer-guide/platform-api/data-world-model/data-mcp.md) is a separate SQL query surface for external MCP clients. The key differences:

|                      | Data-MCP                     | Platform Functions                                                                                                                |
| -------------------- | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| **Integration**      | External MCP client required | Built into the agent reasoning pipeline                                                                                           |
| **Access**           | SQL queries only             | SQL + Python + AI operations                                                                                                      |
| **Tool resolution**  | Separate from context graph  | State-gated through `tool_call_specs` in the standard HSM runtime; native/realtime runtimes can also attach shared tools globally |
| **Write capability** | Read-only                    | Read-only (world model writes go through dedicated write tools, not platform functions)                                           |
| **Loading**          | Manual                       | Loaded at session start from the workspace function store                                                                         |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.amigo.ai/developer-guide/platform-api/functions.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.