Agents

Agents are automated workflows that monitor your systems and take action on your behalf. Each agent can have multiple sessions, which represent individual execution runs with their own message history and lifecycle.

Service: firetiger.nxagent.v2.AgentService

Resource name patterns: agents/{agent_id} and agents/{agent_id}/sessions/{session_id}

Access: Read-write

Resource types: Agent, Session

Example flow

Create an agent, send it a message (which auto-creates a session), then read the conversation back.

1. Create an agent

curl -X POST "https://api.ft-kernel.firetigerapi.com/firetiger.nxagent.v2.AgentService/CreateAgent" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "error-monitor",
    "agent": {
      "title": "Error Rate Monitor",
      "prompt": "You monitor production services for elevated error rates.",
      "connections": [
        {"name": "connections/prod-postgres", "enabled_tools": ["TOOL_POSTGRES_QUERY"]},
        {"name": "connections/prod-prometheus", "enabled_tools": ["TOOL_PROMQL_QUERY"]}
      ],
      "state": "AGENT_STATE_ON"
    }
  }'

2. Send a message (auto-creates a session)

Writing to parent instead of session auto-creates a new session. The default write mode (WRITE_MODE_CHECKPOINT) triggers the agent to start processing.

curl -X POST "https://api.ft-kernel.firetigerapi.com/firetiger.nxagent.v2.AgentService/Write" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "parent": "agents/error-monitor",
    "messages": [
      {
        "@type": "type.googleapis.com/firetiger.nxagent.v1.Activity",
        "user": {
          "text": {"text": "Check error rates for the payments service over the last hour."}
        }
      }
    ]
  }'

{"session": "agents/error-monitor/sessions/ses-abc123", "sessionLength": "1"}

3. Read messages back

Use the session name from the Write response to read the conversation. The agent’s responses will appear as assistant activities.

curl -X POST "https://api.ft-kernel.firetigerapi.com/firetiger.nxagent.v2.AgentService/Read" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"session": "agents/error-monitor/sessions/ses-abc123", "session_offset": 0}'

{
  "session": "agents/error-monitor/sessions/ses-abc123",
  "sessionOffset": "0",
  "sessionLength": "3",
  "messages": [
    {
      "@type": "type.googleapis.com/firetiger.nxagent.v1.Activity",
      "user": {"text": {"text": "Check error rates for the payments service over the last hour."}}
    },
    {
      "@type": "type.googleapis.com/firetiger.nxagent.v1.Activity",
      "assistant": {
        "text": {"text": "I'll query Prometheus for the payments service error rate."},
        "toolCalls": [{"id": "tc-1", "name": "TOOL_PROMQL_QUERY", "arguments": "{\"query\": \"rate(http_requests_total{service=\\\"payments\\\",status=~\\\"5..\\\"}[1h])\"}"}]
      }
    },
    {
      "@type": "type.googleapis.com/firetiger.nxagent.v1.Activity",
      "user": {
        "toolResults": [{"toolCallId": "tc-1", "content": "{\"status\":\"success\",\"data\":{\"result\":[{\"value\":\"0.02\"}]}}"}]
      }
    }
  ],
  "status": "STATUS_EXECUTING"
}

Write vs CreateSession: Use CreateSession when you need an empty session with metadata (like associated resources). Use Write with parent to create a session and send a message in one call.

Methods

Method	Description
CreateAgent	Create a new agent
GetAgent	Retrieve an agent by name
ListAgents	List agents with filtering and pagination
UpdateAgent	Update an existing agent
DeleteAgent	Soft-delete an agent
UndeleteAgent	Restore a soft-deleted agent
CreateSession	Create a new session for an agent
GetSession	Retrieve a session by name
UpdateSession	Update an existing session
DeleteSession	Soft-delete a session
ListSessions	List sessions for an agent or across all agents
DescribeSessions	List sessions with runtime state (status, conclusion, last message)
Write	Send messages to a session
Read	Read messages from a session
GetArtifact	Retrieve an artifact from a session

CreateAgent

Create a new agent.

POST /firetiger.nxagent.v2.AgentService/CreateAgent

Request body

Field	Type	Required	Description
`agent_id`	string	Yes	ID for the new agent (alphanumeric, hyphens, underscores; must start with a letter or digit)
`agent`	Agent	No	Initial agent configuration (title, description, prompt, connections)

Example

curl -X POST "https://api.ft-kernel.firetigerapi.com/firetiger.nxagent.v2.AgentService/CreateAgent" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "my-monitor",
    "agent": {
      "title": "Production Error Monitor",
      "description": "Monitors production logs for error spikes and investigates root causes.",
      "prompt": "You are a production error monitor. Check for elevated error rates and investigate anomalies.",
      "connections": [
        {
          "name": "connections/prod-postgres",
          "enabled_tools": ["TOOL_POSTGRES_QUERY"]
        }
      ],
      "state": "AGENT_STATE_ON"
    }
  }'

Response

{
  "agent": {
    "name": "agents/my-monitor",
    "title": "Production Error Monitor",
    "description": "Monitors production logs for error spikes and investigates root causes.",
    "prompt": "You are a production error monitor. Check for elevated error rates and investigate anomalies.",
    "connections": [
      {
        "name": "connections/prod-postgres",
        "enabledTools": ["TOOL_POSTGRES_QUERY"]
      }
    ],
    "state": "AGENT_STATE_ON",
    "createdBy": "user_abc123",
    "createTime": "2024-06-15T10:00:00Z",
    "updateTime": "2024-06-15T10:00:00Z"
  }
}

GetAgent

Retrieve an agent by name.

POST /firetiger.nxagent.v2.AgentService/GetAgent

Request body

Field	Type	Required	Description
`name`	string	Yes	Resource name of the agent (`agents/{agent}`)

Example

curl -X POST "https://api.ft-kernel.firetigerapi.com/firetiger.nxagent.v2.AgentService/GetAgent" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"name": "agents/my-monitor"}'

ListAgents

List agents with optional filtering and pagination.

POST /firetiger.nxagent.v2.AgentService/ListAgents

Request body

Field	Type	Required	Description
`page_size`	integer	No	Maximum results per page
`page_token`	string	No	Token for the next page of results
`filter`	string	No	Filter expression
`order_by`	string	No	Field to sort by (e.g. `create_time desc`). Supported fields: `create_time`, `update_time`
`show_deleted`	boolean	No	Include soft-deleted agents

Example

curl -X POST "https://api.ft-kernel.firetigerapi.com/firetiger.nxagent.v2.AgentService/ListAgents" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"page_size": 10}'

Response

{
  "agents": [
    {
      "name": "agents/my-monitor",
      "title": "Production Error Monitor",
      "state": "AGENT_STATE_ON",
      "createTime": "2024-06-15T10:00:00Z",
      "updateTime": "2024-06-15T10:00:00Z"
    }
  ],
  "nextPageToken": ""
}

UpdateAgent

Update an existing agent. Use update_mask to specify which fields to modify.

POST /firetiger.nxagent.v2.AgentService/UpdateAgent

Request body

Field	Type	Required	Description
`agent`	Agent	Yes	The agent with `name` set and updated fields
`update_mask`	string	No	Comma-separated list of fields to update. If omitted, all provided fields are updated.

Example

curl -X POST "https://api.ft-kernel.firetigerapi.com/firetiger.nxagent.v2.AgentService/UpdateAgent" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": {
      "name": "agents/my-monitor",
      "state": "AGENT_STATE_OFF"
    },
    "update_mask": "state"
  }'

DeleteAgent

Soft-delete an agent. The resource will still be accessible via GetAgent but excluded from ListAgents results unless show_deleted is set.

POST /firetiger.nxagent.v2.AgentService/DeleteAgent

Request body

Field	Type	Required	Description
`name`	string	Yes	Resource name of the agent to delete (`agents/{agent}`)

Example

curl -X POST "https://api.ft-kernel.firetigerapi.com/firetiger.nxagent.v2.AgentService/DeleteAgent" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"name": "agents/my-monitor"}'

UndeleteAgent

Restore a soft-deleted agent.

POST /firetiger.nxagent.v2.AgentService/UndeleteAgent

Request body

Field	Type	Required	Description
`name`	string	Yes	Resource name of the agent to restore (`agents/{agent}`)

Example

curl -X POST "https://api.ft-kernel.firetigerapi.com/firetiger.nxagent.v2.AgentService/UndeleteAgent" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"name": "agents/my-monitor"}'

Response

{
  "agent": {
    "name": "agents/my-monitor",
    "title": "Production Error Monitor",
    "state": "AGENT_STATE_ON",
    "createTime": "2024-06-15T10:00:00Z",
    "updateTime": "2024-06-16T09:00:00Z"
  }
}

CreateSession

Create a new session for an agent, optionally with initial messages.

POST /firetiger.nxagent.v2.AgentService/CreateSession

Request body

Field	Type	Required	Description
`parent`	string	Yes	Parent agent resource name (`agents/{agent}`)
`session_id`	string	No	Session ID to use. If not provided, the server generates one.
`initial_messages`	Any[]	No	Initial messages to write to the session upon creation
`associated_resources`	string[]	No	Resource names to link to this session

Example

curl -X POST "https://api.ft-kernel.firetigerapi.com/firetiger.nxagent.v2.AgentService/CreateSession" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "parent": "agents/my-monitor",
    "session_id": "run-2024-06-15",
    "associated_resources": ["incidents/inc-001"]
  }'

Response

{
  "session": {
    "name": "agents/my-monitor/sessions/run-2024-06-15",
    "associatedResources": ["incidents/inc-001"],
    "createTime": "2024-06-15T14:30:00Z",
    "updateTime": "2024-06-15T14:30:00Z"
  }
}

GetSession

Retrieve a session by name.

POST /firetiger.nxagent.v2.AgentService/GetSession

Request body

Field	Type	Required	Description
`name`	string	Yes	Resource name of the session (`agents/{agent}/sessions/{session}`)

Example

curl -X POST "https://api.ft-kernel.firetigerapi.com/firetiger.nxagent.v2.AgentService/GetSession" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"name": "agents/my-monitor/sessions/run-2024-06-15"}'

UpdateSession

Update an existing session. Use update_mask to specify which fields to modify.

POST /firetiger.nxagent.v2.AgentService/UpdateSession

Request body

Field	Type	Required	Description
`session`	Session	Yes	The session with `name` set and updated fields
`update_mask`	string	No	Comma-separated list of fields to update. If omitted, all provided fields are updated.

Example

curl -X POST "https://api.ft-kernel.firetigerapi.com/firetiger.nxagent.v2.AgentService/UpdateSession" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "session": {
      "name": "agents/my-monitor/sessions/run-2024-06-15",
      "associated_resources": ["incidents/inc-001", "objectives/obj-002"]
    },
    "update_mask": "associated_resources"
  }'

DeleteSession

Soft-delete a session. The resource will still be accessible via GetSession but excluded from ListSessions results unless show_deleted is set.

POST /firetiger.nxagent.v2.AgentService/DeleteSession

Request body

Field	Type	Required	Description
`name`	string	Yes	Resource name of the session to delete (`agents/{agent}/sessions/{session}`)

Example

curl -X POST "https://api.ft-kernel.firetigerapi.com/firetiger.nxagent.v2.AgentService/DeleteSession" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"name": "agents/my-monitor/sessions/run-2024-06-15"}'

ListSessions

List sessions for an agent (or across all agents) with optional filtering and pagination. Returns basic session metadata without runtime state.

POST /firetiger.nxagent.v2.AgentService/ListSessions

Request body

Field	Type	Required	Description
`parent`	string	No	Parent agent resource name (`agents/{agent}`). If empty, lists sessions across all agents.
`page_size`	integer	No	Maximum results per page
`page_token`	string	No	Token for the next page of results
`filter`	string	No	Filter expression (e.g. `create_time >= '2024-01-01T00:00:00Z'`)
`order_by`	string	No	Field to sort by (e.g. `create_time desc`). Supported fields: `create_time`, `update_time`
`show_deleted`	boolean	No	Include soft-deleted sessions

Example

curl -X POST "https://api.ft-kernel.firetigerapi.com/firetiger.nxagent.v2.AgentService/ListSessions" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"parent": "agents/my-monitor", "page_size": 25}'

Response

{
  "sessions": [
    {
      "name": "agents/my-monitor/sessions/run-2024-06-15",
      "associatedResources": ["incidents/inc-001"],
      "createTime": "2024-06-15T14:30:00Z",
      "updateTime": "2024-06-15T14:30:00Z"
    }
  ],
  "nextPageToken": ""
}

DescribeSessions

List sessions with runtime state from the execution engine, including status, session length, last message time, and conclusion. This is a richer alternative to ListSessions.

POST /firetiger.nxagent.v2.AgentService/DescribeSessions

Request body

Field	Type	Required	Description
`parent`	string	No	Parent agent resource name (`agents/{agent}`). If empty, describes sessions across all agents.
`page_size`	integer	No	Maximum results per page
`page_token`	string	No	Token for the next page of results
`filter`	string	No	Filter expression
`order_by`	string	No	Field to sort by (e.g. `create_time desc`). Supported fields: `create_time`, `update_time`
`show_deleted`	boolean	No	Include soft-deleted sessions

Example

curl -X POST "https://api.ft-kernel.firetigerapi.com/firetiger.nxagent.v2.AgentService/DescribeSessions" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{"parent": "agents/my-monitor", "page_size": 10}'

Response

Returns a list of SessionDescription objects:

{
  "sessionDescriptions": [
    {
      "session": {
        "name": "agents/my-monitor/sessions/run-2024-06-15",
        "associatedResources": ["incidents/inc-001"],
        "createTime": "2024-06-15T14:30:00Z",
        "updateTime": "2024-06-15T14:30:00Z"
      },
      "status": "STATUS_WAITING",
      "sessionLength": 12,
      "lastMessage": "2024-06-15T15:45:00Z",
      "conclusion": {
        "done": {
          "message": "Investigation complete. Root cause identified as a memory leak in the auth service introduced in v2.3.",
          "issues": [
            {
              "title": "Auth service memory leak",
              "description": "Memory usage grows linearly under load, causing OOM kills after ~4 hours of peak traffic."
            }
          ]
        }
      }
    }
  ],
  "nextPageToken": ""
}

Write

Send messages to an agent session. Messages are wrapped in google.protobuf.Any and typically contain Activity protos. The @type field on each message tells the server how to decode it — for user messages, use type.googleapis.com/firetiger.nxagent.v1.Activity. A checkpoint write (the default) triggers the agent to process the new messages.

You can target an existing session by name, or provide a parent agent to auto-create a new session.

POST /firetiger.nxagent.v2.AgentService/Write

Request body

Field	Type	Required	Description
`session`	string	No	Resource name of the session to write to (`agents/{agent}/sessions/{session}`). Either `session` or `parent` must be set.
`parent`	string	No	Parent agent resource name (`agents/{agent}`). If set (and `session` is empty), a new session is auto-created.
`messages`	Any[]	Yes	Messages to write (must not be empty). Each message is a `google.protobuf.Any` with an `@type` field.
`write_mode`	string	No	How to write: `WRITE_MODE_CHECKPOINT` (default, triggers agent), `WRITE_MODE_PROVISIONAL` (queued silently), or `WRITE_MODE_PROVISIONAL_OR_CHECKPOINT` (provisional if agent is running, checkpoint if idle).

Example – send a user message to a session

curl -X POST "https://api.ft-kernel.firetigerapi.com/firetiger.nxagent.v2.AgentService/Write" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "session": "agents/my-monitor/sessions/run-2024-06-15",
    "messages": [
      {
        "@type": "type.googleapis.com/firetiger.nxagent.v1.Activity",
        "user": {
          "text": {"text": "Check the error rates for the payments service in the last hour."}
        }
      }
    ]
  }'

Example – auto-create a session and send a message

curl -X POST "https://api.ft-kernel.firetigerapi.com/firetiger.nxagent.v2.AgentService/Write" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "parent": "agents/my-monitor",
    "messages": [
      {
        "@type": "type.googleapis.com/firetiger.nxagent.v1.Activity",
        "user": {
          "text": {"text": "Investigate elevated 500 errors on the checkout endpoint."}
        }
      }
    ]
  }'

Response

{
  "session": "agents/my-monitor/sessions/ses-abc123",
  "sessionLength": "1"
}

Read

Read messages from an agent session starting from a given offset. Returns the full conversation history as a list of google.protobuf.Any messages (typically Activity protos).

POST /firetiger.nxagent.v2.AgentService/Read

Request body

Field	Type	Required	Description
`session`	string	Yes	Resource name of the session (`agents/{agent}/sessions/{session}`)
`session_offset`	integer	No	Start reading from this message index (0-based). Defaults to 0.

Example

curl -X POST "https://api.ft-kernel.firetigerapi.com/firetiger.nxagent.v2.AgentService/Read" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "session": "agents/my-monitor/sessions/run-2024-06-15",
    "session_offset": 0
  }'

Response

{
  "session": "agents/my-monitor/sessions/run-2024-06-15",
  "sessionOffset": "0",
  "sessionLength": "3",
  "messages": [
    {
      "@type": "type.googleapis.com/firetiger.nxagent.v1.Activity",
      "user": {
        "text": {"text": "Check the error rates for the payments service."}
      },
      "timestamp": "2024-06-15T14:30:00Z"
    },
    {
      "@type": "type.googleapis.com/firetiger.nxagent.v1.Activity",
      "assistant": {
        "text": {"text": "I'll query the error rates now."},
        "toolCalls": [
          {"id": "tc-1", "name": "TOOL_PROMQL_QUERY", "arguments": "{\"query\": \"rate(http_requests_total{status=~\\\"5..\\\"}[1h])\"}"}
        ]
      },
      "timestamp": "2024-06-15T14:30:05Z"
    },
    {
      "@type": "type.googleapis.com/firetiger.nxagent.v1.Activity",
      "user": {
        "toolResults": [
          {"toolCallId": "tc-1", "content": "{\"status\":\"success\",\"data\":{\"result\":[{\"value\":\"0.05\"}]}}"}
        ]
      },
      "timestamp": "2024-06-15T14:30:10Z"
    }
  ],
  "status": "STATUS_WAITING"
}

GetArtifact

Retrieve an artifact from a session by its SHA-256 hash.

POST /firetiger.nxagent.v2.AgentService/GetArtifact

Request body

Field	Type	Required	Description
`session`	string	Yes	Resource name of the session (`agents/{agent}/sessions/{session}`)
`sha256`	string	Yes	SHA-256 hash of the artifact to retrieve

Example

curl -X POST "https://api.ft-kernel.firetigerapi.com/firetiger.nxagent.v2.AgentService/GetArtifact" \
  -u "$USERNAME:$PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "session": "agents/my-monitor/sessions/run-2024-06-15",
    "sha256": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
  }'