Runtime Contract v1¶

The HTTP interface every hosted agent serves on its port (default 8080). The platform exposes it at https://<slug>.run.agntspark.com. Official templates and the default runtime image implement it; your own images should too.

`GET /health`¶

Ready:

200
{"status": "ok", "contract": "v1", "agent_id": "agt_…"}

Running but unable to answer, e.g. no model API key:

503
{"status": "unconfigured", "error": "No API key configured for provider 'openai'…"}

`POST /invoke`¶

Request:

{"input": "How do I reset my password?", "session_id": "optional"}

Field	Type
`input`	string	Required. The user's message.
`session_id`	string	Optional. Omit to start a conversation; send back the one you received to continue it.

Response:

200
{"output": "Go to Settings → Security …", "session_id": "5f0c…", "agent_id": "agt_…"}

The agent may call its tools several times before answering; /invoke returns only the final answer.

`GET /`¶

Describes the agent:

{
  "agent_id": "agt_…",
  "name": "support",
  "provider": "openai",
  "model": "gpt-4o",
  "template": "customer-support",
  "tools": ["search_knowledge_base", "analyze_sentiment", "create_ticket"],
  "contract": "v1"
}

Errors¶

{"error": {"code": "INVALID_REQUEST", "message": "…"}}

Status	When
`400`	The body isn't valid, e.g. `input` is missing.
`502`	The model provider returned an error.
`503`	The agent isn't configured.
`500`	Anything else.

Requests refused by the platform before reaching the agent (401, 404, 429, 503 in plain text) are described in Access Keys and Rate Limits.

Sessions¶

Conversation history is kept in memory, per replica, and is lost when the agent restarts or is redeployed. See Scaling.

Configuration¶

The runtime reads, highest precedence first:

Environment set by the platform: AGENT_ID, AGENT_NAME, SYSTEM_PROMPT (when not empty), LLM_MODEL, LLM_PROVIDER, and the provider key OPENAI_API_KEY, ANTHROPIC_API_KEY or GOOGLE_API_KEY.
A template directory named by AGNTSPARK_TEMPLATE_DIR, containing agent.yaml.
Defaults: gpt-4o and a generic assistant prompt.