Platform Functions

SQL, Python, AI, and UDTF functions that give agents direct access to world model data and analytics during conversations, with endpoints to register, invoke, test, list, and delete them.

Platform functions are the universal tool primitive for agent data access. You register a SQL query, Python function, or AI composition, and agents can call it during conversations. No container, no deployment pipeline. The function runs on the platform's compute layer and returns results directly to the agent.

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.

Conceptual overview. For background on function types, built-in functions, and how functions relate to Actions and Skills, see the Platform Functions conceptual docs.

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

Every platform function surfaces as a tool in the agent's context graph. The agent sees a tool name, description, input schema, and result.

Named Functions

Pre-registered functions with fixed input schemas. The agent calls them by name. All named function tool IDs use the fn_ prefix (e.g., fn_caller_history, fn_entity_confidence).

The platform ships with built-in functions covering entity confidence assessment, caller history, patient summaries, intent classification, clinical extraction, PII redaction, care plan generation, handoff summaries, urgency assessment, and memory access. See the conceptual docs for the full list.

Long-Tail and Ad Hoc Queries

For questions no named function anticipates, use workspace data queries (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. Any registered function or query with a description becomes an agent tool, gated per context-graph state through tool_call_specs. If a function is not in the current state's spec, the agent cannot see or call it.

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"

Endpoints

All endpoints are workspace-scoped under /v1/{workspace_id}/functions.

Method	Path	Description
GET	/v1/{workspace_id}/functions	List registered functions
GET	/v1/{workspace_id}/functions/{function_name}	Get a registered function
PUT	/v1/{workspace_id}/functions/{function_name}	Deploy or update a function
DELETE	/v1/{workspace_id}/functions/{function_name}	Delete a function
POST	/v1/{workspace_id}/functions/{function_name}/invoke	Invoke a function
POST	/v1/{workspace_id}/functions/{function_name}/test	Test a function and persist test telemetry

Deploy or Update a Function

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

Deploy (validate + upsert) a platform function

put

Validate + upsert a platform function row.

Atomic: validation + (python/udtf only) UC UDF materialization + upsert into platform.functions happen as one logical operation. Repeat deploys against the same (workspace, name) replace the row in place and clear stale last_test_* telemetry.

The function name comes from the URL path; the request body's name field must match or a 400 is raised. The URL is the authoritative source.

Permissions: admin, owner.

Authorizations

BearerAuth

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

function_namestringRequired

Body

application/json

The authored shape of a platform function.

Identical wire format whether it's authored as a YAML file in the repo or POSTed to /v1/{ws}/functions/deploy. The deploy pipeline validates this, derives the JSON Schema for the LLM tool spec, and INSERTs a row into platform.functions with the next monotonic version per (workspace_id, name). For python / udtf rows, deploy ALSO issues CREATE OR REPLACE FUNCTION against the warehouse to materialize the UC UDF.

namestring · min: 1 · max: 128RequiredPattern: ^[a-z][a-z0-9_]*$

descriptionstring · min: 1 · max: 2048Required

when_to_usestring · max: 2048OptionalDefault: ""

function_typestring · enumOptionalDefault: sqlPossible values:

returnsstring · enumOptionalDefault: tablePossible values:

returns_typestring · enumOptionalDefault: stringPossible values:

bodystring · min: 1 · max: 8192Required

timeout_msinteger · min: 100 · max: 60000OptionalDefault: 30000

Responses

200

Successful Response

application/json

Single row from platform.functions.

namestringRequired

function_typestringRequired

returns_kindstringRequired

descriptionstringOptionalDefault: ""

when_to_usestringOptionalDefault: ""

sql_templatestringRequired

timeout_msintegerOptionalDefault: 30000

last_test_atstring · nullableOptional

last_test_statusstring · nullableOptional

last_test_errorstring · nullableOptional

last_test_duration_msinteger · nullableOptional

deployed_atstring · nullableOptional

deployed_bystring · nullableOptional

400

URL function_name does not match body name

422

Validation failure (read-only / bind / parity)

429

Rate limited

put/v1/{workspace_id}/functions/{function_name}

HTTPcURLJavaScriptPython

PUT /v1/{workspace_id}/functions/{function_name} HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 397

{
  "name": "text",
  "description": "text",
  "when_to_use": "",
  "function_type": "sql",
  "returns": "table",
  "returns_type": "string",
  "parameters": [
    {
      "name": "text",
      "type": "string",
      "description": "text",
      "default": "text"
    }
  ],
  "returns_columns": [
    {
      "name": "text",
      "type": "string",
      "description": ""
    }
  ],
  "body": "text",
  "timeout_ms": 30000,
  "examples": [
    {
      "input": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "output": null,
      "description": ""
    }
  ]
}

{
  "name": "text",
  "function_type": "text",
  "returns_kind": "text",
  "description": "",
  "when_to_use": "",
  "parameters": [
    {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  ],
  "sql_template": "text",
  "input_schema": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "examples": [
    {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  ],
  "timeout_ms": 30000,
  "last_test_at": "text",
  "last_test_status": "text",
  "last_test_error": "text",
  "last_test_duration_ms": 1,
  "deployed_at": "text",
  "deployed_by": "text"
}

Example

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.

List every platform function registered in the workspace

get

List every platform function registered in the workspace.

Permissions: Workspace.view (read role and above).

Authorizations

BearerAuth

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

Responses

200

Successful Response

application/json

countintegerRequired

429

Rate limited

get/v1/{workspace_id}/functions

HTTPcURLJavaScriptPython

GET /v1/{workspace_id}/functions HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "items": [
    {
      "name": "text",
      "function_type": "text",
      "returns_kind": "text",
      "description": "",
      "when_to_use": "",
      "parameters": [
        {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        }
      ],
      "sql_template": "text",
      "input_schema": {
        "ANY_ADDITIONAL_PROPERTY": "anything"
      },
      "examples": [
        {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        }
      ],
      "timeout_ms": 30000,
      "last_test_at": "text",
      "last_test_status": "text",
      "last_test_error": "text",
      "last_test_duration_ms": 1,
      "deployed_at": "text",
      "deployed_by": "text"
    }
  ],
  "count": 1
}

Get a Function

Returns a single registered function.

Get a registered platform function by name

get

Resolve a function by name.

Permissions: Workspace.view (read role and above).

Authorizations

BearerAuth

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

function_namestringRequired

Responses

200

Successful Response

application/json

Single row from platform.functions.

namestringRequired

function_typestringRequired

returns_kindstringRequired

descriptionstringOptionalDefault: ""

when_to_usestringOptionalDefault: ""

sql_templatestringRequired

timeout_msintegerOptionalDefault: 30000

last_test_atstring · nullableOptional

last_test_statusstring · nullableOptional

last_test_errorstring · nullableOptional

last_test_duration_msinteger · nullableOptional

deployed_atstring · nullableOptional

deployed_bystring · nullableOptional

404

Function not found

422

Validation Error

application/json

429

Rate limited

get/v1/{workspace_id}/functions/{function_name}

HTTPcURLJavaScriptPython

GET /v1/{workspace_id}/functions/{function_name} HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "name": "text",
  "function_type": "text",
  "returns_kind": "text",
  "description": "",
  "when_to_use": "",
  "parameters": [
    {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  ],
  "sql_template": "text",
  "input_schema": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "examples": [
    {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    }
  ],
  "timeout_ms": 30000,
  "last_test_at": "text",
  "last_test_status": "text",
  "last_test_error": "text",
  "last_test_duration_ms": 1,
  "deployed_at": "text",
  "deployed_by": "text"
}

Invoke a Function

Executes a registered function with caller-supplied arguments.

Execute a registered platform function

post

Execute a registered function and return its rows.

Bound parameters are validated against the stored schema; ws_id is auto-injected from the request context. Returns the executor's shaped response (rows for returns=table, scalar value for returns=scalar).

Permissions: Workspace.view (read role and above). Read-only keys are intentionally allowed — invocation runs a stored, pre-validated SELECT against catalogs the workspace SP already has SELECT on; the gate on what can run is the deploy-time validator (read-only invariant), not the per-call permission.

Authorizations

BearerAuth

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

function_namestringRequired

Body

application/json

Invoke a registered function with caller-supplied args.

Responses

200

Successful Response

application/json

resultanyOptional

duration_msnumberOptionalDefault: 0

row_countintegerOptionalDefault: 0

404

Function not found

422

Bind validation failure

429

Rate limited

post/v1/{workspace_id}/functions/{function_name}/invoke

HTTPcURLJavaScriptPython

POST /v1/{workspace_id}/functions/{function_name}/invoke HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 48

{
  "input": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  }
}

{
  "result": null,
  "duration_ms": 0,
  "row_count": 0
}

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.

Test invoke + persist last_test_* telemetry on the row

post

Test invoke — same as invoke + persists last_test_* on the row.

Returns 200 with status="fail" + populated error on execution failure (instead of a 5xx) so the DC has a single happy-path rendering.

Permissions: admin, owner.

Authorizations

BearerAuth

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

function_namestringRequired

Body

application/json

Invoke a registered function with caller-supplied args.

Responses

200

Successful Response

application/json

Response shape for POST /v1/{ws}/functions/{name}/test.

Structural superset of :class:InvokeResponse. Adds status and error so the DC can render the executor's failure detail inline rather than a generic "Invocation failed." The underlying invoke uses the same path; status / error are filled in by service.test after catching any HTTPException (503) from the executor, so the route never bubbles a 5xx for a logical SQL failure — it's still a 200 with status=fail so the caller can show the message.

Invariant (enforced by :func:_check_error_when_fail): status == "fail" → error is not None and len(error) > 0.

resultanyOptional

duration_msnumberOptionalDefault: 0

row_countintegerOptionalDefault: 0

statusstringOptionalDefault: pass

errorstring · max: 2000 · nullableOptional

test_duration_msinteger · nullableOptional

404

Function not found

422

Validation Error

application/json

429

Rate limited

post/v1/{workspace_id}/functions/{function_name}/test

HTTPcURLJavaScriptPython

POST /v1/{workspace_id}/functions/{function_name}/test HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 48

{
  "input": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  }
}

{
  "result": null,
  "duration_ms": 0,
  "row_count": 0,
  "status": "pass",
  "error": "text",
  "test_duration_ms": 1
}

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.

Remove a registered platform function

delete

Remove a registered function row.

Permissions: admin, owner.

Authorizations

BearerAuth

AuthorizationstringRequired

API key issued via POST /v1/{workspace_id}/api-keys. Pass the returned api_key value as a Bearer token.

Path parameters

workspace_idstring · uuidRequired

function_namestringRequired

Responses

204

Successful Response

No content

404

Function not found

422

Validation Error

application/json

429

Rate limited

delete/v1/{workspace_id}/functions/{function_name}

HTTPcURLJavaScriptPython

DELETE /v1/{workspace_id}/functions/{function_name} HTTP/1.1
Host: api.platform.amigo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

No content

Permissions: Admin or Owner role.

Registered Function Object

Field	Type	Description
name	string	Function name
function_type	string	sql, ai, python, or udtf
returns_kind	string	table or scalar
description	string	Function description
when_to_use	string	Tool-selection guidance
parameters	array	Parameter declarations
sql_template	string	Stored executable template
input_schema	object	JSON Schema derived from parameters
examples	array	Example inputs and outputs
timeout_ms	integer	Execution timeout
last_test_at	string or null	Last test timestamp
last_test_status	string or null	Last test result
last_test_error	string or null	Last test error
last_test_duration_ms	integer or null	Last test duration
deployed_at	string or null	Deployment timestamp
deployed_by	string or null	Deploying principal

CLI

Platform functions can be managed through Agent Forge:

forge platform function list       # List registered functions
forge platform function get        # Show a single function definition
forge platform function deploy     # Validate and upsert a function by name
forge platform function invoke     # Execute a function with arguments
forge platform function test       # Test with sample input
forge platform function delete     # Remove a function

Comparison with Data-MCP

Platform functions are the primitive for agent data access; Data-MCP 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
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