API reference

Every method is served by the Hub three ways, with the same token scopes and results:

• REST/JSON: POST /agen.v1.HubService/<Method> with a JSON body and Authorization: Bearer <token>.
• gRPC / Connect: service agen.v1.HubService (spec/proto/agen/v1/hub.proto).
• MCP: tool <snake_case name> at /mcp (streamable HTTP).

Fields use protojson names; bytes are base64; 64-bit integers may be strings.

CancelTask

Cancel a task that has not finished; a running run is stopped.

Scope: operator · REST: POST /agen.v1.HubService/CancelTask · MCP tool: cancel_task

Field	Type	Description
id	string
tree	bool	Cancel every unfinished task of id’s whole tree (its root and every descendant, found through root_task_id), not just id itself.
mode	string	“” or “hard” (default): stop at once. “graceful”: each task of id (or, with tree, of the whole tree) currently leased or running gets a “cancel” run_inbox entry first (surfaced to the model as a request to wrap up and call finish), and this call waits up to grace_period_seconds for all of them to end on their own before falling through to the same hard stop “hard” does for whatever is still unfinished. A queued or waiting task is always stopped at once, graceful or not: there is no live turn to give a last chance to.
gracePeriodSeconds	int32	Only with mode “graceful”. 0: a default (20s); capped at 5 minutes.

CreateApiToken

Create an API token with scopes (viewer, operator, approver, admin), optionally limited to namespaces.

Scope: admin · REST: POST /agen.v1.HubService/CreateApiToken · MCP tool: create_api_token

Field	Type	Description
name	string
scopes	list of string
namespaces	list of string
ttlSeconds	int32
onBehalf	bool	For an agent that works for people (the assistant): each MCP call must name the task it serves (_meta agen/taskId, which Agen sets), and runs with the scopes and namespaces that both this token and the task’s submitter hold. It can never decide approvals.
trust	string	The trust tasks submitted with this token get (3.7): operator, trusted (default) or untrusted.

CreateDeployment

Deploy a bundle (files in bundleFiles or bundleText) as a new deployment. With validateOnly, only check it and return warnings.

Scope: operator · REST: POST /agen.v1.HubService/CreateDeployment · MCP tool: create_deployment

Field	Type	Description
namespace	string
name	string	Defaults to the bundle name.
bundleFiles	map<string, bytes>	The bundle files. The Hub validates and stores them as a Definition.
bundleText	map<string, string>	Bundle files as text (merged with bundle_files; easier to write by hand or from an MCP client than base64).
validateOnly	bool	Check the bundle and settings and return warnings without deploying.
kind	DeploymentKind	Overrides for values from x-agen/config.json; unset means use the bundle.
scale	ScalePolicy
placement	Placement
budget	Budget
limits	Limits
triggers	list of Trigger
conversations	ConversationPolicy

CreateJoinToken

A single-use token for enrolling a Nest (agen nest run –join-token).

Scope: admin · REST: POST /agen.v1.HubService/CreateJoinToken · MCP tool: create_join_token

Field	Type	Description
ttlSeconds	int32

CreateWebhookSecret

Create (or rotate) the secret a webhook trigger’s callers must present.

Scope: operator · REST: POST /agen.v1.HubService/CreateWebhookSecret · MCP tool: create_webhook_secret

Field	Type	Description
ref	DeploymentRef
trigger	string

DecideApproval

Approve or deny an approval. The principal whose work asked cannot decide it.

Scope: approver · REST: POST /agen.v1.HubService/DecideApproval · MCP tool: decide_approval

Field	Type	Description
id	string
approve	bool

DeleteDeployment

Delete a deployment; its instances stop.

Scope: operator · REST: POST /agen.v1.HubService/DeleteDeployment · MCP tool: delete_deployment

Field	Type	Description
ref	DeploymentRef

DeleteNotificationTarget

Remove a notification target.

Scope: admin · REST: POST /agen.v1.HubService/DeleteNotificationTarget · MCP tool: delete_notification_target

Field	Type	Description
namespace	string
name	string

DeleteSecret

Delete a platform secret.

Scope: admin · REST: POST /agen.v1.HubService/DeleteSecret · MCP tool: delete_secret

Field	Type	Description
namespace	string
name	string

GetActivity

What is happening now: every unfinished run with what it is doing (model, tool, waiting for an agent or an approval), queues, and warnings worth a look.

Scope: viewer · REST: POST /agen.v1.HubService/GetActivity · MCP tool: get_activity

Field	Type	Description
namespace	string	Empty: every namespace the caller may see.

GetArtifact

One artifact by id (3.8, part): named, content-addressed text an agent saved during a run with the save_artifact tool.

Scope: viewer · REST: POST /agen.v1.HubService/GetArtifact · MCP tool: get_artifact

Field	Type	Description
namespace	string
id	string

GetBundleGuide

How bundles are laid out, the JSON Schema of every bundle file and a complete example bundle.

Scope: viewer · REST: POST /agen.v1.HubService/GetBundleGuide · MCP tool: get_bundle_guide

GetCassette

A run’s recorded interactions (3.6, part: agen replay), if its deployment had recordInteractions on when it ran. Not found: it never recorded one.

Scope: viewer · REST: POST /agen.v1.HubService/GetCassette · MCP tool: get_cassette

Field	Type	Description
runId	string	A run id: a task’s runId (GetTask), or from ListRuns or GetTrace.

GetDefinition

One bundle version with its files (text files also as textFiles).

Scope: viewer · REST: POST /agen.v1.HubService/GetDefinition · MCP tool: get_definition

Field	Type	Description
digest	string

GetDeployment

A deployment and its instances (with the tools each loaded and their tool servers’ state).

Scope: viewer · REST: POST /agen.v1.HubService/GetDeployment · MCP tool: get_deployment

Field	Type	Description
ref	DeploymentRef

GetLogs

Operational log lines of a deployment: runs, instance and task lifecycle.

Scope: viewer · REST: POST /agen.v1.HubService/GetLogs · MCP tool: get_logs

Field	Type	Description
ref	DeploymentRef
instanceId	string
limit	int32
since	Timestamp	Only lines after this time.

GetMetrics

Runs, failures, duration percentiles, tokens and cost per deployment over a time window, who calls whom, and per served model.

Scope: viewer · REST: POST /agen.v1.HubService/GetMetrics · MCP tool: get_metrics

Field	Type	Description
namespace	string	Empty: every namespace the caller may see.
windowSeconds	int32	Window length (default 86400, at most 30 days).
buckets	int32	Number of time buckets per deployment (default 24, at most 200).

GetTask

A task and its result; waitSeconds (up to 300) waits for it to finish.

Scope: viewer · REST: POST /agen.v1.HubService/GetTask · MCP tool: get_task

Field	Type	Description
id	string
waitSeconds	int32	Wait up to this many seconds (at most 300) for the task to finish; the task is returned as it is when the wait ends.

GetTaskTree

Every task in the tree a given task belongs to (its root’s descendants, including the root itself), oldest first (3.4, part).

Scope: viewer · REST: POST /agen.v1.HubService/GetTaskTree · MCP tool: get_task_tree

Field	Type	Description
taskId	string	Any task in the tree; the response covers its root and every one of the root’s descendants.

GetTrace

The spans of a trace: model calls, tool calls and delegations across agents.

Scope: viewer · REST: POST /agen.v1.HubService/GetTrace · MCP tool: get_trace

Field	Type	Description
traceId	string

GetTranscript

A run’s conversation: the messages it sent and received (tool calls and results included) and the system prompt.

Scope: viewer · REST: POST /agen.v1.HubService/GetTranscript · MCP tool: get_transcript

Field	Type	Description
runId	string	A run id: a task’s runId (get_task), or from list_runs or get_trace.
includeHistory	bool	Also the earlier messages of the conversation the run continued.

ListApiTokens

API tokens (never their secrets).

Scope: admin · REST: POST /agen.v1.HubService/ListApiTokens · MCP tool: list_api_tokens

ListApprovals

Approvals (“ask” permissions) that wait for a decision, or past ones.

Scope: approver · REST: POST /agen.v1.HubService/ListApprovals · MCP tool: list_approvals

Field	Type	Description
namespace	string
state	ApprovalState

ListArtifacts

A namespace’s artifacts, newest first; optionally one task’s.

Scope: viewer · REST: POST /agen.v1.HubService/ListArtifacts · MCP tool: list_artifacts

Field	Type	Description
namespace	string
taskId	string

ListDefinitions

Bundle versions (definitions), without their files.

Scope: viewer · REST: POST /agen.v1.HubService/ListDefinitions · MCP tool: list_definitions

Field	Type	Description
name	string
ref	DeploymentRef	The versions this deployment has run, most recently used first (name is then ignored).

ListDeployments

Deployments in a namespace (“” = every namespace the token may see).

Scope: viewer · REST: POST /agen.v1.HubService/ListDeployments · MCP tool: list_deployments

Field	Type	Description
namespace	string	Empty means all namespaces the caller may see.

ListEvalReports

A deployment’s eval reports, newest first (2.43, part).

Scope: viewer · REST: POST /agen.v1.HubService/ListEvalReports · MCP tool: list_eval_reports

Field	Type	Description
ref	DeploymentRef
limit	int32	0: the default (20).

ListEvents

The event log, oldest first after a cursor: tasks queued, started and finished (with their outcome), approvals, budget thresholds, provider holds, warnings, missed triggers, deployment changes. wait_seconds waits for the next event.

Scope: viewer · REST: POST /agen.v1.HubService/ListEvents · MCP tool: list_events

Field	Type	Description
namespace	string	Empty: every namespace the caller may see.
afterSeq	int64	Events after this seq (0: from the oldest kept).
types	list of string	Only these types; a type ending in “.” matches a prefix (“task.”).
deployment	string
labels	map<string, string>	Only events whose labels include all of these.
severity	string	Only events at least this severe: info, warning or critical.
limit	int32	At most this many events (default 100, at most 1000).
waitSeconds	int32	Wait up to this long (at most 300) for a first matching event.

ListFeedback

Feedback, filtered by deployment, labels and time, newest first.

Scope: viewer · REST: POST /agen.v1.HubService/ListFeedback · MCP tool: list_feedback

Field	Type	Description
namespace	string
deployment	string
labels	map<string, string>
since	Timestamp	Only feedback recorded at or after this time.
limit	int32

ListInstances

Every instance on every Nest, with state, running tasks and loaded tools.

Scope: viewer · REST: POST /agen.v1.HubService/ListInstances · MCP tool: list_instances

Field	Type	Description
namespace	string
deployment	string
nestId	string

ListMemoryBlocks

A namespace’s memory blocks, newest-updated first.

Scope: viewer · REST: POST /agen.v1.HubService/ListMemoryBlocks · MCP tool: list_memory_blocks

Field	Type	Description
namespace	string

ListNests

Enrolled Nests (machines or clusters that run instances).

Scope: viewer · REST: POST /agen.v1.HubService/ListNests · MCP tool: list_nests

ListNotificationTargets

Notification targets (never their secrets).

Scope: admin · REST: POST /agen.v1.HubService/ListNotificationTargets · MCP tool: list_notification_targets

Field	Type	Description
namespace	string

ListProviderHolds

Provider accounts held after an account error (invalid key, no credit): their deployments take no new work until one probe succeeds.

Scope: viewer · REST: POST /agen.v1.HubService/ListProviderHolds · MCP tool: list_provider_holds

ListRuns

Runs (one per task or A2A call), newest first, with usage and cost. Filter by status, labels and time; roots_only lists traces.

Scope: viewer · REST: POST /agen.v1.HubService/ListRuns · MCP tool: list_runs

Field	Type	Description
namespace	string	Empty: every namespace the caller may see.
deployment	string
limit	int32	Runs per page (default 50, at most 500), newest first.
status	string	running, waiting_approval, succeeded, failed or cancelled.
rootsOnly	bool	Only runs that started a trace (rootsOnly; not delegated runs), with the usage of their whole run tree.
labels	map<string, string>	Runs carrying all of these labels.
since	Timestamp	Runs started at or after this time.
pageToken	string	nextPageToken of the previous page.
taskId	string	The run(s) of one task (a task’s attempts resume one run).

ListSecrets

Platform secret names in a namespace (never values).

Scope: admin · REST: POST /agen.v1.HubService/ListSecrets · MCP tool: list_secrets

Field	Type	Description
namespace	string

ListTasks

Recent tasks, newest first.

Scope: viewer · REST: POST /agen.v1.HubService/ListTasks · MCP tool: list_tasks

Field	Type	Description
namespace	string
deployment	string
state	TaskState
limit	int32
scheduled	bool	Only tasks waiting for their start time (not_before), soonest first.

ListTemplates

Ready-made agent bundles to start from.

Scope: viewer · REST: POST /agen.v1.HubService/ListTemplates · MCP tool: list_templates

ListTriggerEvents

Trigger firings: fired, missed (Hub down) and rejected (bad credentials).

Scope: viewer · REST: POST /agen.v1.HubService/ListTriggerEvents · MCP tool: list_trigger_events

Field	Type	Description
ref	DeploymentRef	Empty name: every deployment (of the namespace, or of every namespace the caller may see when the namespace is empty too).
state	TriggerEventState
limit	int32

PauseDeployment

Pause (stop all instances and hold at 0) or resume a deployment.

Scope: operator · REST: POST /agen.v1.HubService/PauseDeployment · MCP tool: pause_deployment

Field	Type	Description
ref	DeploymentRef
paused	bool	false resumes.
holdRuns	bool	Also hold every currently unfinished task of the deployment (2.8), the deployment-wide form of PauseTask/PauseTree: a leased/running one suspends at its next model call, a queued/waiting one stays put. Ignored (nothing to hold) when paused is false; a resume (paused: false) always clears any hold this put in place, whether or not hold_runs is set on that call.
until	Timestamp	hold_runs only: the hold’s deadline. Unset: holds until explicitly resumed.
reason	string

PauseTask

Hold a task: a queued one is skipped by leasing, a running one suspends at its next model call (3.4, part).

Scope: operator · REST: POST /agen.v1.HubService/PauseTask · MCP tool: pause_task

Field	Type	Description
id	string
tree	bool	Hold every unfinished task of id’s whole tree (its root and every descendant, found through root_task_id), not just id itself. Mirrors CancelTask’s tree, including async/detached children.
until	Timestamp	Unset: held until ResumeTask, with no deadline.
reason	string

QueryTask

A task’s progress, current activity and outcome, without waiting on it like GetTask’s wait_seconds does (3.4, part).

Scope: viewer · REST: POST /agen.v1.HubService/QueryTask · MCP tool: query_task

Field	Type	Description
id	string

RecordEvalReport

Records an agen eval report against a deployment (2.43, part: eval history), so a later agen deploy --require-eval can compare against it.

Scope: operator · REST: POST /agen.v1.HubService/RecordEvalReport · MCP tool: record_eval_report

Field	Type	Description
ref	DeploymentRef
definitionDigest	string
reportJson	string

RecordFeedback

Record a judgement on how a task went (a person, a check, or a judge model); approval decisions are recorded this way too.

Scope: operator · REST: POST /agen.v1.HubService/RecordFeedback · MCP tool: record_feedback

Field	Type	Description
taskId	string
score	double	0.0 (worst) to 1.0 (best).
labels	map<string, string>
note	string

RequestWake

Start a sleeping deployment (scale it to at least 1).

Scope: operator · REST: POST /agen.v1.HubService/RequestWake · MCP tool: request_wake

Field	Type	Description
ref	DeploymentRef

Resolve

A2A endpoints of a deployment and a short-lived call token for them.

Scope: viewer · REST: POST /agen.v1.HubService/Resolve · MCP tool: resolve

Field	Type	Description
ref	DeploymentRef
caller	DeploymentRef	NestService only: the deployment of the instance that will call (its Manager asks on its behalf); the call token names it as the caller.

ResumeProvider

End a provider hold now (e.g. after fixing the key or adding credit).

Scope: operator · REST: POST /agen.v1.HubService/ResumeProvider · MCP tool: resume_provider

Field	Type	Description
account	string

ResumeTask

End a hold started by PauseTask, now or early.

Scope: operator · REST: POST /agen.v1.HubService/ResumeTask · MCP tool: resume_task

Field	Type	Description
id	string
tree	bool	End the hold on every task of id’s whole tree, not just id itself.

RevokeApiToken

Revoke an API token.

Scope: admin · REST: POST /agen.v1.HubService/RevokeApiToken · MCP tool: revoke_api_token

Field	Type	Description
id	string

RevokeNest

Revokes a Nest’s credentials (bearer token and client certificate) and reschedules its instances elsewhere.

Scope: admin · REST: POST /agen.v1.HubService/RevokeNest · MCP tool: revoke_nest

Field	Type	Description
id	string

ScaleDeployment

Set the desired number of instances (within scale.min..max).

Scope: operator · REST: POST /agen.v1.HubService/ScaleDeployment · MCP tool: scale_deployment

Field	Type	Description
ref	DeploymentRef
desired	int32

SetMemoryBlock

Replace a memory block’s value outright, creating it if it does not exist yet (3.10). Agents change one through the memory_update tool instead, which compares versions first.

Scope: operator · REST: POST /agen.v1.HubService/SetMemoryBlock · MCP tool: set_memory_block

Field	Type	Description
namespace	string
id	string
label	string
description	string
value	string
limitChars	int64	0: no limit.

SetNotificationTarget

Add or replace a namespace’s notification target: a URL the Hub POSTs events to, signed with a secret it returns once.

Scope: admin · REST: POST /agen.v1.HubService/SetNotificationTarget · MCP tool: set_notification_target

Field	Type	Description
target	NotificationTarget

SetSecret

Set a platform secret (bundle secrets with source “platform”), for named deployments. Values never come back out.

Scope: admin · REST: POST /agen.v1.HubService/SetSecret · MCP tool: set_secret

Field	Type	Description
namespace	string
name	string
value	string
deployments	list of string	The deployments (in this namespace) allowed to read it; at least one.

SubmitTask

Queue a task (one agent run) for a deployment. Use conversationKey to continue an earlier conversation.

Scope: operator · REST: POST /agen.v1.HubService/SubmitTask · MCP tool: submit_task

Field	Type	Description
ref	DeploymentRef
input	string
idempotencyKey	string	Optional client key; resubmitting the same key returns the same task.
conversationKey	string	Tasks with the same key continue one conversation (and its memory).
labels	map<string, string>	Free-form labels, copied to runs, tool calls and delegated tasks.
modelTier	string	Cost tier for a routing model; see Task.model_tier.
notBefore	Timestamp	Run no earlier than this (a scheduled task); unset: as soon as possible.
overrides	TaskOverrides	Narrow what this task may do: tools, skills, a system prompt addendum, extra deny/ask rules and run limits.
notAfter	Timestamp	Not leased after this time: fails as “expired” instead of waiting indefinitely for capacity.
scheduleKey	string	At most one queued task per (deployment, schedule_key); submitting again with the same key cancels the queued task that already has it.
priority	string	Lease order within this deployment’s queue: urgent, high, normal or background. Empty: normal.
trust	string	A trust at most this high (3.7): narrows the submitting principal’s own trust, never raises it. Empty: the principal’s trust as is.
locks	list of string	Extra locks this task needs, on top of the deployment’s own locks config (3.11, part): it waits in the queue until it can take all of them at once, then holds them until it ends.
onParentEnd	string	Temporal’s parent-close policy for this task’s own children (3.4, part): “cancel” (default, also empty) or “abandon”. See Task.on_parent_end.
delivery	string	Override the conversation’s own conversations.queueMode (followup, collect, steer or interrupt) for this submission only. Empty: use the deployment’s policy. Has no effect without conversation_key.

UpdateDeployment

Roll out a new bundle version and/or change a deployment’s scale, budget, limits, triggers or placement.

Scope: operator · REST: POST /agen.v1.HubService/UpdateDeployment · MCP tool: update_deployment

Field	Type	Description
ref	DeploymentRef
bundleFiles	map<string, bytes>	New bundle version; empty keeps the current one.
scale	ScalePolicy
budget	Budget
limits	Limits
triggers	list of Trigger	Replaces the trigger set when non-empty.
placement	Placement
bundleText	map<string, string>
validateOnly	bool
conversations	ConversationPolicy

WhoAmI

The caller’s identity, scopes and namespaces.

Scope: viewer · REST: POST /agen.v1.HubService/WhoAmI · MCP tool: who_am_i