Cloud Agent Control Plane

Cloud Agent Control Plane

SessionFS coordinates AI agents across local tools and cloud platforms through one shared control plane: personas, tickets, project knowledge, and rules. This page covers integrating cloud agents — Amazon Bedrock, Google Vertex/Gemini, and any custom HTTP-callable agent — directly with the SessionFS REST API.

This is a control-plane integration: cloud agents can participate in your team's personas, tickets, knowledge, and rules. Transcript capture as .sfs sessions is not part of this layer — that ships in a future release. Until then, what your cloud agent says inside its own platform stays there; what it does against SessionFS (tickets, knowledge contributions) is captured here.

This page covers agent-initiated runs — the cloud agent itself calls the REST API. If instead a coordination layer (a script, n8n, a GitHub Action, a Claude Code session) spawns an external CLI agent (Codex CLI, Gemini CLI, Claude Code) to do ticket work, see External Agent Orchestration for the create_agent_run → spawn → complete_agent_run provenance wrapper.

What cloud agents can do today

| Capability | Endpoint(s) | Tier | |---|---|---| | List + load personas (atlas, prism, scribe, ...) | GET /api/v1/projects/{project_id}/personas[/{name}] | Pro+ | | List, create, start, complete tickets | GET/POST /api/v1/projects/{project_id}/tickets[/{ticket_id}/{start,complete}] | Team+ | | Get the compiled persona + ticket context for a started ticket | Returned by POST /tickets/{ticket_id}/start | Team+ | | Add knowledge entries (decisions, patterns, bugs, ...) | POST /api/v1/projects/{project_id}/entries/add | Paid | | Search knowledge | GET /api/v1/projects/{project_id}/entries?search=... | Paid | | Fetch canonical project rules | GET /api/v1/projects/{project_id}/rules | Paid | | Resolve project + compiled context by git remote | GET /api/v1/projects/{git_remote_normalized} | Paid |

All operations require Authorization: Bearer <SessionFS_API_key>. As of v0.10.10, scoped service API keys (created at POST /api/v1/orgs/{org_id}/service-keys) are the recommended credential for cloud agents — they are org-scoped, expirable, and restricted to a specific scope set (e.g. tickets:write, knowledge:write, agent_runs:write). Your existing user bearer tokens still work for prototyping.

Why this is not MCP

MCP works great for local tools (Claude Code, Cursor, Codex, etc.) where the agent runtime can spawn sfs mcp serve as a stdio subprocess. Bedrock, Vertex, and custom cloud agents typically can't. The Cloud Agent Control Plane gives those agents the same operations through plain HTTP, with no client-side daemon, no MCP transport, and no special SDK.

If your agent can speak MCP, prefer it — you get 68 tools and richer descriptions. If it can't, use this layer.

Amazon Bedrock

Bedrock agents call out to AWS Lambdas for every action group operation. SessionFS ships two reference artifacts:

1. OpenAPI spec — docs/integrations/bedrock-action-group.yaml

Import this file when creating a Bedrock Action Group. It declares 10 operations:

listPersonas        — GET  /api/v1/projects/{project_id}/personas
getPersona          — GET  /api/v1/projects/{project_id}/personas/{name}
listTickets         — GET  /api/v1/projects/{project_id}/tickets
createTicket        — POST /api/v1/projects/{project_id}/tickets
startTicket         — POST /api/v1/projects/{project_id}/tickets/{ticket_id}/start
completeTicket      — POST /api/v1/projects/{project_id}/tickets/{ticket_id}/complete
addKnowledge        — POST /api/v1/projects/{project_id}/entries/add
searchKnowledge     — GET  /api/v1/projects/{project_id}/entries
getRules            — GET  /api/v1/projects/{project_id}/rules
getProjectContext   — GET  /api/v1/projects/{git_remote_normalized}

2. Lambda reference handler — docs/integrations/bedrock_lambda.py

A 220-line Python 3.12 handler that:

• Parses the Bedrock action-group event (messageVersion, apiPath, httpMethod, parameters, requestBody).
• Dispatches to the matching SessionFS HTTP endpoint via an internal operation table that mirrors the OpenAPI spec.
• Reads SESSIONFS_API_URL + SESSIONFS_API_KEY from the Lambda's environment. In production, fetch SESSIONFS_API_KEY from AWS Secrets Manager rather than env directly — the env path is for quick testing.
• Returns a Bedrock-compatible response envelope.

Uses only urllib.request so it runs on the vanilla Lambda Python runtime with no packaging dependencies.

Deploy

1. Create a Lambda from bedrock_lambda.py (Python 3.12 runtime; handler bedrock_lambda.lambda_handler).
2. Grant the Lambda permission to read your SessionFS API key from Secrets Manager.
3. Set SESSIONFS_API_URL (default https://api.sessionfs.dev works for cloud-hosted SessionFS).
4. In the Bedrock agent console: create an action group, point it at the Lambda, and upload bedrock-action-group.yaml as the API schema.
5. Bedrock validates the schema, generates tool descriptions for the agent, and routes function calls through your Lambda.

Google Vertex / Gemini

Vertex agents use function calling (google-generativeai ≥ 0.7). SessionFS ships:

docs/integrations/vertex_tools.py

This file is two things in one:

1. FUNCTION_DECLARATIONS — a list of 10 function-declaration dicts (name, description, parameters in OpenAPI-subset JSON Schema). Convert them with genai.protos.FunctionDeclaration(**decl) in your agent runtime.
2. call_sessionfs_function(name, args) — a reference handler that maps a Gemini function-call result back into a SessionFS HTTP request. Deploy as a Cloud Function or Cloud Run service that proxies tool calls from your Vertex agent.

from google.generativeai import protos
from vertex_tools import FUNCTION_DECLARATIONS, call_sessionfs_function

tools = [protos.Tool(function_declarations=[
    protos.FunctionDeclaration(**d) for d in FUNCTION_DECLARATIONS
])]

# In your message loop:
response = model.generate_content(prompt, tools=tools)
for fc in response.candidates[0].content.parts:
    if fc.function_call:
        result = call_sessionfs_function(fc.function_call.name, dict(fc.function_call.args))
        # Feed `result` back into the model as a function-response part.

Cloud Function entry point

vertex_tools.cloud_function_entrypoint(request) is a Flask-style HTTP handler ready to deploy. Wire your Vertex agent's function-call loop to POST {"name": "...", "args": {...}} to that URL.

Custom HTTP agents

If you're rolling your own (LangChain, LlamaIndex, custom agent runtime, internal AI gateway, ...), you don't need either reference handler. Just speak HTTP:

curl -X POST "$SESSIONFS_API_URL/api/v1/projects/$PROJECT_ID/tickets/$TICKET_ID/start?tool=generic" \
  -H "Authorization: Bearer $SESSIONFS_API_KEY"

The OpenAPI spec at docs/integrations/bedrock-action-group.yaml doubles as a generic API reference for the control plane — the operationIds are platform-neutral.

Recommended workflow

A cloud agent kicking off a piece of work typically does:

1. getProjectContext to load the project's compiled context document.
2. getRules to learn project-wide constraints.
3. listTickets (filtered to its assigned persona) to find work.
4. startTicket on the chosen ticket — the response includes the compiled persona + ticket context as markdown. Feed this back into the model as system prompt / role context.
5. Do the work (writing code, drafting docs, etc.).
6. addKnowledge for any decisions or discoveries surfaced during the work.
7. completeTicket with notes + changed_files when done. The ticket moves to review and propagates completion notes to dependents.

Authentication

Scoped service API keys (v0.10.10+, recommended for cloud agents). Create a service key scoped to the capabilities your agent needs:

curl -X POST "$SESSIONFS_API_URL/api/v1/orgs/$ORG_ID/service-keys" \
  -H "Authorization: Bearer $ADMIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "bedrock-atlas-agent",
    "scopes": ["tickets:write", "knowledge:write", "personas:read", "rules:read", "agent_runs:write"],
    "expires_at": "2026-12-31T23:59:59Z",
    "project_ids": ["proj_abc"]
  }'

The response includes the raw key exactly once — copy it into AWS Secrets Manager (Bedrock Lambda) or Google Secret Manager (Vertex). The list/detail endpoints only return the key_prefix going forward.

Service keys are deny-by-default at the route layer: get_current_user rejects them with 403 service_key_not_allowed, and a key only reaches a handler via require_scope("tickets:write") style dependencies. Cross-org access is blocked at the project boundary. Audit rows (HandoffEvent, AgentRun, TicketComment, KnowledgeEntry, RetrievalAuditEvent) record actor_type="service_key" + service_key_id + service_key_name so service-key activity is distinguishable from human activity.

Structured error codes: api_key_revoked, api_key_expired, service_key_not_allowed, insufficient_scope (with required/current arrays), cross_org_denied.

Legacy user bearer tokens still work (their scopes back-fill to ["*"]) but are not recommended for cloud agents. If you ship a personal token to Lambda, treat it like any production secret — load from AWS Secrets Manager or Google Secret Manager, never bake into Lambda/Cloud Function source.

What this does NOT include

To keep this release thin and reviewable:

• No transcript / session capture. Cloud agents don't yet upload .sfs sessions. That ships separately.
• No new server endpoints. Everything is the v0.10.2 shipped API.
• Bearer tokens only at the wire layer. Service keys (v0.10.10) and user keys both ride the standard Authorization: Bearer ... header — no new client-side flow.
• No broad CORS changes. Lambda and Cloud Functions are server-to-server callers; CORS would only matter for browser-hosted cloud agents, which is not in scope.
• No new ticket fields for platform routing. If you need to know which cloud platform executed a ticket, that's an AgentRun design — open a follow-up.

See also

• External Agent Orchestration — wrap a spawned Codex/Gemini/Claude Code CLI agent in an AgentRun for ticket-scoped provenance.
• CI Integration (Agent Runs) — gate a CI build on a persona review's outcome.
• MCP Server — full MCP tool catalogue, including the 14 persona + ticket tools.
• MCP integration — preferred path for local tools (Claude Code, Cursor, Codex, ...).
• CLI reference — sfs persona, sfs ticket, sfs project entries — the same operations from a terminal.