Applications

An application is a workflow that serves inference. It is a chat or completion endpoint you build, version, and invoke through Agenta. The underlying artifact is a workflow with the is_application: true flag; the /applications/* endpoints give you defaults and shortcuts tailored to that case.

Agenta ships two built-in application types:

Type	What it does
completion	Single-turn prompt completion. Takes inputs, returns a structured output.
chat	Multi-turn chat. Takes a message history, returns the next message.

Custom workflows are also applications. They let you point Agenta at your own HTTP handler or code, so the prompt, model parameters, and runtime behaviour live in your service while versioning, deployment, and invocation stay in Agenta.

Each revision can be used in two ways: invoked directly through Agenta's hosted runtime, or read for its configuration so your own runtime picks up the latest prompt and parameters.

For commit semantics, include_archived, and how revision IDs stay stable, see Versioning. For the broader workflow model that applications specialise, see Workflows. The rest of this page covers what is specific to applications.

Body

An application revision commits a data payload that describes what runs.

Field	What it describes
data.uri	Locates the handler. Built-in URIs (agenta:builtin:completion:v0, agenta:builtin:chat:v0) point at Agenta's hosted runtime. A custom URI (agenta:custom:hook:v0, agenta:custom:code:v0) points at a custom workflow.
data.url	Populated by the server. The HTTP endpoint that serves this application. Clients POST to {url}/invoke.
data.schemas	JSON Schemas for parameters (the prompt configuration), inputs (the request payload), and outputs (the response shape).
data.parameters	The configuration: prompt messages, model, tools, response format, and so on.

uri and schemas together determine what the application does and what payloads it takes. Both come from a template chosen at create time.

How it runs

To invoke an application, retrieve the current revision first, then POST to its data.url.

# 1. Retrieve the revision that a variant currently points to.
curl -X POST "$AGENTA_HOST/api/applications/revisions/retrieve" \
  -H "Content-Type: application/json" \
  -H "Authorization: ApiKey $AGENTA_API_KEY" \
  -d '{"application_variant_ref": {"slug": "support-bot.default"}}'

The response contains application_revision.data.url, application_revision.data.parameters, and application_revision.data.schemas.

# 2. Invoke the application at its service URL.
curl -X POST "https://$AGENTA_HOST/services/completion/v0/invoke" \
  -H "Content-Type: application/json" \
  -H "Authorization: ApiKey $AGENTA_API_KEY" \
  -d '{
    "data": {
      "inputs": {"country": "France"},
      "parameters": {
        "prompt": {
          "messages": [
            {"role": "system", "content": "You are an expert in geography."},
            {"role": "user", "content": "What is the capital of {{country}}?"}
          ],
          "llm_config": {"model": "gpt-4o-mini"}
        }
      }
    }
  }'

The response returns outputs matching data.schemas.outputs, plus a trace_id for the invocation's trace.

For inputs already stored in Agenta (a specific revision, an environment ref), the SDK resolves the URL and parameters automatically. The REST pattern shown here is the explicit version.

Catalog

Applications are created from a template. Each template describes the handler URI and the JSON Schemas an application of that type uses. Built-in templates include completion, chat, hook (custom HTTP), and code (custom code).

# List available templates.
curl -X GET "$AGENTA_HOST/api/applications/catalog/templates/" \
  -H "Authorization: ApiKey $AGENTA_API_KEY"

# Inspect one.
curl -X GET "$AGENTA_HOST/api/applications/catalog/templates/completion" \
  -H "Authorization: ApiKey $AGENTA_API_KEY"

Templates may also have presets: named configurations that scaffold a variant's first revision. Templates and presets are global, read-only, and version with the product.

Deployment

Applications can be deployed to named environments (for example, development, staging, production). Deployment writes a reference from the environment revision to the application revision under a key (by default {application_slug}.revision).

# Deploy a specific revision to an environment.
curl -X POST "$AGENTA_HOST/api/applications/revisions/deploy" \
  -H "Content-Type: application/json" \
  -H "Authorization: ApiKey $AGENTA_API_KEY" \
  -d '{
    "application_variant_ref": {"id": "019d952f-0000-0000-0000-000000000001"},
    "environment_ref": {"slug": "production"}
  }'

Once deployed, clients retrieve the currently deployed revision by environment rather than by variant:

curl -X POST "$AGENTA_HOST/api/applications/revisions/retrieve" \
  -H "Content-Type: application/json" \
  -H "Authorization: ApiKey $AGENTA_API_KEY" \
  -d '{
    "environment_ref": {"slug": "production"},
    "key": "support-bot.revision"
  }'

If key is omitted and the application reference has a resolvable slug, the server derives it as {application_slug}.revision.

Simple endpoints

The /simple/applications/ surface collapses the artifact, variant, and latest revision into one flat record with the handler URL and merged schemas. POST /simple/applications/query returns one row per application; POST /simple/applications/ creates the artifact, default variant, and first revision in a single call.

Use the simple surface when you want the "current application" without tracking lineage. For commits, forks, or specific-revision retrieval, use /applications/, /applications/variants/, and /applications/revisions/. See Simple Endpoints for the general pattern.

Example

Create an application, commit a new revision, and invoke it.

# 1. Create the application + default variant + first revision.
curl -X POST "$AGENTA_HOST/api/simple/applications/" \
  -H "Content-Type: application/json" \
  -H "Authorization: ApiKey $AGENTA_API_KEY" \
  -d '{
    "application": {
      "slug": "geo-qa",
      "name": "geo-qa",
      "flags": {"is_application": true},
      "data": {
        "uri": "agenta:builtin:completion:v0",
        "parameters": {
          "prompt": {
            "messages": [
              {"role": "system", "content": "You are an expert in geography."},
              {"role": "user", "content": "What is the capital of {{country}}?"}
            ],
            "llm_config": {"model": "gpt-4o-mini"}
          }
        }
      }
    }
  }'

The response includes id, variant_id, revision_id, and data.url.

# 2. Commit a new revision on the same variant.
curl -X POST "$AGENTA_HOST/api/applications/revisions/commit" \
  -H "Content-Type: application/json" \
  -H "Authorization: ApiKey $AGENTA_API_KEY" \
  -d '{
    "application_revision_commit": {
      "application_variant_id": "019d952f-0000-0000-0000-000000000001",
      "message": "Tighter system prompt",
      "data": {
        "uri": "agenta:builtin:completion:v0",
        "parameters": {
          "prompt": {
            "messages": [
              {"role": "system", "content": "Answer only geography questions. Refuse everything else."},
              {"role": "user", "content": "What is the capital of {{country}}?"}
            ],
            "llm_config": {"model": "gpt-4o-mini"}
          }
        }
      }
    }
  }'

# 3. Retrieve the latest revision and get its URL.
curl -X POST "$AGENTA_HOST/api/applications/revisions/retrieve" \
  -H "Content-Type: application/json" \
  -H "Authorization: ApiKey $AGENTA_API_KEY" \
  -d '{"application_variant_ref": {"id": "019d952f-0000-0000-0000-000000000001"}}'

# 4. Invoke at the URL returned in data.url.
curl -X POST "https://$AGENTA_HOST/services/completion/v0/invoke" \
  -H "Content-Type: application/json" \
  -H "Authorization: ApiKey $AGENTA_API_KEY" \
  -d '{"data": {"inputs": {"country": "France"}, "parameters": { /* from step 3 */ }}}'

Lifecycle

Applications and their variants are soft-deleted. Archiving hides the resource from queries unless include_archived: true is sent in the request body. Revision IDs remain resolvable after archive so historical traces still link to their origin. See Versioning.