Unary · Agents
Gets details about a specific agent run, including its metadata, specification,
and status (phase, error messages, and usage statistics).
Use this method to:
- Monitor the run’s progress
- Retrieve the agent’s conversation URL
- Check if an agent run is actively producing output
Examples
-
Get agent run details by ID:
agentExecutionId: "6fa1a3c7-fbb7-49d1-ba56-1890dc7c4c35"
Endpoint
POST /api/gitpod.v1.AgentService/GetAgentExecution
https://app.ona.com with that domain.
Request example
export ONA_HOST=https://app.ona.com
export ONA_API_KEY=<your-token>
curl --request POST \
--url "$ONA_HOST/api/gitpod.v1.AgentService/GetAgentExecution" \
--header "Authorization: Bearer $ONA_API_KEY" \
--header "Content-Type: application/json" \
--data '{
"agentExecutionId": "<agent-execution-id>"
}'
import gitpod.v1.agent_pb2 as agent_pb2
from ona_sdk import create_client_from_env
ona = create_client_from_env()
request = agent_pb2.GetAgentExecutionRequest(
agent_execution_id="<agent-execution-id>",
)
response = ona.services.agent.get_agent_execution(request)
print(response)
import { create } from "@bufbuild/protobuf";
import { createClientFromEnv } from "@gitpod/sdk";
import { GetAgentExecutionRequestSchema } from "@gitpod/sdk/gitpod/v1/agent_pb";
async function main() {
const ona = createClientFromEnv();
const request = create(GetAgentExecutionRequestSchema, {
agentExecutionId: "<agent-execution-id>",
});
const response = await ona.services.agent.getAgentExecution(request);
console.log(response);
}
main().catch(console.error);
package main
import (
"context"
"fmt"
"log"
"connectrpc.com/connect"
"github.com/gitpod-io/gitpod-sdk-go/sdk"
gitpodpb "github.com/gitpod-io/gitpod-sdk-go/v1"
)
func main() {
ona, err := sdk.NewFromEnv()
if err != nil {
log.Fatal(err)
}
request := connect.NewRequest(&gitpodpb.GetAgentExecutionRequest{
AgentExecutionId: "<agent-execution-id>",
})
response, err := ona.Services.Agent.GetAgentExecution(context.Background(), request)
if err != nil {
log.Fatal(err)
}
fmt.Println(response.Msg)
}
{
"agentExecutionId": "<agent-execution-id>"
}
Request
gitpod.v1.GetAgentExecutionRequest
| Field | Type | Required | Description |
|---|---|---|---|
agentExecutionId | string | No | Constraints: string.uuid=true. |
Response
gitpod.v1.GetAgentExecutionResponse
| Field | Type | Required | Description |
|---|---|---|---|
agentExecution | AgentExecution | No |
Related types
AgentExecution
AgentExecution
gitpod.v1.AgentExecution| Field | Type | Required | Description |
|---|---|---|---|
id | string | No | ID is a unique identifier of this agent run. No other agent run with the same name must be managed by this agent manager |
metadata | Metadata | No | Metadata is data associated with this agent that’s required for other parts of Gitpod to function |
spec | Spec | No | Spec is the configuration of the agent that’s required for the runner to start the agent |
status | Status | No | Status is the current status of the agent |
Metadata
Metadata
gitpod.v1.AgentExecution.Metadata| Field | Type | Required | Description |
|---|---|---|---|
name | string | No | |
description | string | No | |
creator | Subject | No | |
createdAt | RFC 3339 timestamp | No | |
updatedAt | RFC 3339 timestamp | No | |
role | AgentExecutionRole | No | role is the role of the agent execution |
workflowActionId | string | No | workflow_action_id is set when this agent execution was created as part of a workflow. Used to correlate agent executions with their parent workflow execution action. Constraints: ignore=1, string.uuid=true. |
annotations | map of string to string | No | annotations are key-value pairs for tracking external context. |
sessionId | string | No | session_id is the ID of the session this agent execution belongs to. |
Spec
Spec
gitpod.v1.AgentExecution.Spec| Field | Type | Required | Description |
|---|---|---|---|
specVersion | 64-bit integer string | No | version of the spec. The value of this field has no semantic meaning (e.g. don’t interpret it as as a timestamp), but it can be used to impose a partial order. If a.spec_version < b.spec_version then a was the spec before b. |
session | string | No | |
desiredPhase | Phase | No | desired_phase is the desired phase of the agent run |
agentId | string | No | Constraints: string.uuid=true. |
codeContext | AgentCodeContext | No | |
limits | Limits | No | |
codexSettings | CodexSettings | No | codex_settings contains persisted desired/manual settings for the Codex app agent. |
Status
Status
gitpod.v1.AgentExecution.Status| Field | Type | Required | Description |
|---|---|---|---|
statusVersion | 64-bit integer string | No | version of the status. The value of this field has no semantic meaning (e.g. don’t interpret it as as a timestamp), but it can be used to impose a partial order. If a.status_version < b.status_version then a was the status before b. |
session | string | No | |
phase | Phase | No | |
failureMessage | string | No | failure_message contains the reason the agent run failed to operate. |
warningMessage | string | No | warning_message contains warnings, e.g. when the LLM is overloaded. |
failureReason | AgentExecutionFailureReason | No | failure_reason contains a structured reason code for the failure. |
conversationUrl | string | No | conversation_url is the URL to the conversation (all messages exchanged between the agent and the user) of the agent run. |
transcriptUrl | string | No | transcript_url is the URL to the LLM transcript (all messages exchanged between the agent and the LLM) of the agent run. |
supportBundleUrl | string | No | support_bundle_url is the URL to download a diagnostic bundle for this agent execution. |
conversationUrls | ConversationURLs | No | conversation_urls contains the v2 conversation streaming endpoints. When present, clients should use these URLs instead of conversation_url. |
iterations | 64-bit integer string | No | |
inputTokensUsed | 64-bit integer string | No | |
outputTokensUsed | 64-bit integer string | No | |
contextWindowLength | 64-bit integer string | No | |
cachedCreationTokensUsed | 64-bit integer string | No | |
cachedInputTokensUsed | 64-bit integer string | No | |
contextWindowLimit | 64-bit integer string | No | context_window_limit is the selected model’s maximum context window size in tokens. |
judgement | string | No | judgement is the judgement of the agent run produced by the judgement prompt. |
currentOperation | CurrentOperation | No | current_operation is the current operation of the agent execution. |
usedEnvironments | array of EnvironmentUsage | No | used_environments is the list of environments that were used by the agent execution. |
currentActivity | string | No | current_activity is the current activity description of the agent execution. |
outputs | map of string to OutputValue | No | outputs is a map of key-value pairs that can be set by the agent during execution. Similar to task execution outputs, but with typed values for structured data. Constraints: map.keys.string.max_len=128, map.keys.string.min_len=1. |
supportedModel | SupportedModel | No | supported_model is the LLM model being used by the agent execution. |
llmCapabilities | LLMCapabilities | No | llm_capabilities describes provider capabilities for the selected LLM integration. |
mode | AgentMode | No | mode is the current operational mode of the agent execution. This is set by the agent when entering different modes (e.g., Ralph mode via /ona:ralph command). |
mcpIntegrationStatuses | array of MCPIntegrationStatus | No | mcp_integration_statuses contains the status of all MCP integrations used by this agent execution |
waitingInfo | WaitingInfo | No | waiting_info is set when phase is PHASE_WAITING_FOR_INPUT and the agent has registered interests (timers, sub-agent completions, user messages). |
terminalId | string | No | terminal_id is the ID of the terminal running the agent, if the agent runs as a terminal service (runsOn: terminal). |
goal | Goal | No | goal projects the current agent goal, if any. |
codexSettings | CodexSettings | No | codex_settings contains runtime effective settings reported by the Codex app agent. |
subagents | array of Subagent | No |
Phase
Phase
| Value | Number | Description |
|---|---|---|
PHASE_UNSPECIFIED | 0 | The phase is not set. |
PHASE_PENDING | 10 | The agent run is pending. |
PHASE_RUNNING | 20 | The agent run is active. |
PHASE_WAITING_FOR_INPUT | 30 | The agent run is waiting for input. |
PHASE_STOPPED | 40 | The agent run is inactive. |
AgentExecutionFailureReason
AgentExecutionFailureReason
AgentExecutionFailureReason represents the reason why an agent execution failed
| Value | Number | Description |
|---|---|---|
AGENT_EXECUTION_FAILURE_REASON_UNSPECIFIED | 0 | |
AGENT_EXECUTION_FAILURE_REASON_ENVIRONMENT | 1 | The agent execution failed due to environment issues |
AGENT_EXECUTION_FAILURE_REASON_SERVICE | 2 | The agent execution failed due to service issues |
AGENT_EXECUTION_FAILURE_REASON_LLM_INTEGRATION | 3 | The agent execution failed due to LLM integration issues |
AGENT_EXECUTION_FAILURE_REASON_INTERNAL | 4 | Deprecated. Deprecated: The agent execution failed due to internal errors Use AGENT_EXECUTION_FAILURE_REASON_AGENT_EXECUTION instead |
AGENT_EXECUTION_FAILURE_REASON_AGENT_EXECUTION | 5 | The agent execution failed due to agent execution errors |
AgentExecutionRole
AgentExecutionRole
AgentExecutionRole represents the role of an agent execution
| Value | Number | Description |
|---|---|---|
AGENT_EXECUTION_ROLE_UNSPECIFIED | 0 | |
AGENT_EXECUTION_ROLE_DEFAULT | 1 | Default role for agent executions |
AGENT_EXECUTION_ROLE_WORKFLOW | 2 | Workflow role for agent executions that are part of a workflow |
AgentMode
AgentMode
AgentMode defines the operational mode of an agent
| Value | Number | Description |
|---|---|---|
AGENT_MODE_UNSPECIFIED | 0 | Default execution mode - standard agent behavior |
AGENT_MODE_EXECUTION | 1 | Execution mode - agent performs tasks and makes changes |
AGENT_MODE_PLANNING | 2 | Planning mode - agent focuses on analysis and planning |
AGENT_MODE_RALPH | 3 | Ralph mode - autonomous planning and implementation mode |
AGENT_MODE_SPEC | 4 | Spec mode - planning phase followed by interactive implementation |
AGENT_MODE_GOAL | 5 | Goal mode - agent treats the user input as a goal objective |
SupportedModel
SupportedModel
SupportedModel enumerates the LLM models available for agent executions
| Value | Number | Description |
|---|---|---|
SUPPORTED_MODEL_UNSPECIFIED | 0 | |
SUPPORTED_MODEL_SONNET_3_5 | 1 | |
SUPPORTED_MODEL_SONNET_3_7 | 2 | |
SUPPORTED_MODEL_SONNET_3_7_EXTENDED | 3 | |
SUPPORTED_MODEL_SONNET_4 | 4 | |
SUPPORTED_MODEL_SONNET_4_EXTENDED | 5 | |
SUPPORTED_MODEL_SONNET_4_5 | 8 | |
SUPPORTED_MODEL_SONNET_4_5_EXTENDED | 9 | |
SUPPORTED_MODEL_SONNET_4_6 | 18 | |
SUPPORTED_MODEL_SONNET_4_6_EXTENDED | 19 | |
SUPPORTED_MODEL_SONNET_5 | 32 | |
SUPPORTED_MODEL_OPUS_4 | 6 | |
SUPPORTED_MODEL_OPUS_4_EXTENDED | 7 | |
SUPPORTED_MODEL_OPUS_4_5 | 14 | |
SUPPORTED_MODEL_OPUS_4_5_EXTENDED | 15 | |
SUPPORTED_MODEL_OPUS_4_6 | 16 | |
SUPPORTED_MODEL_OPUS_4_6_EXTENDED | 17 | |
SUPPORTED_MODEL_OPUS_4_7 | 22 | |
SUPPORTED_MODEL_OPUS_4_8 | 31 | |
SUPPORTED_MODEL_HAIKU_4_5 | 21 | |
SUPPORTED_MODEL_OPENAI_4O | 10 | |
SUPPORTED_MODEL_OPENAI_4O_MINI | 11 | |
SUPPORTED_MODEL_OPENAI_O1 | 12 | |
SUPPORTED_MODEL_OPENAI_O1_MINI | 13 | |
SUPPORTED_MODEL_OPENAI_AUTO | 23 | SUPPORTED_MODEL_OPENAI_AUTO flags a request as OpenAI-bound without encoding a specific model slug. The actual model is chosen by the client (today: native Codex via ~/.codex/config.toml) and captured from the upstream Responses-API response.model field for metering and rate-card lookup. This keeps the proto stable across OpenAI model-catalog churn. Reserved numbers 24-30 are intentionally left free for future OpenAI routing sentinels if we ever need to distinguish sub-families. |