kagent

package
v0.4.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 11, 2026 License: MIT Imports: 20 Imported by: 0

Documentation

Overview

Package kagent implements the parts of the kagent runtime contract that a non-ADK harness must satisfy to run behind the kagent A2A gateway.

The gateway does not read task state from the runtime: it reads kagent's own PostgreSQL store. A runtime that only keeps tasks in memory therefore streams a correct answer and then fails the call, because the gateway cannot find the task it is supposed to publish. That failure is visible as:

Code: NotFound
Message: task not found
ErrorInfo reason TASK_NOT_FOUND

The runtime's half of the contract is the private gRPC TaskStoreService: CreateTask, UpdateTask, GetTask, ListTasks and SettleTask. This package implements the a2a-go task store interface on top of that service so the SDK persists every task where the gateway can read it.

Index

Constants

View Source
const DispatchHeader = "x-kagent-dispatch-id"

DispatchHeader carries the gateway's attempt fence to the runtime task store. Sending it with the first save lets the gateway prove the input it reserved a dispatch for was accepted, so a failed send can safely be retried.

View Source
const (
	// IdentityDir is the directory Substrate projects runtime identity into.
	IdentityDir = "/run/kagent/identity"
)

Runtime identity files, projected by the Substrate runtime and rebound on actor restore. The session ID is the actor name without its "session-" prefix.

View Source
const RuntimeActorTokenPlaceholder = "placeholder"

RuntimeActorTokenPlaceholder is sent as the Authorization bearer value on every runtime RPC. Substrate egress rewrites that header at the control-plane origin into a short-lived Actor JWT for the kagent-runtime audience, so the value is never a usable credential of its own. kagent rejects runtime calls that omit the header, which is why a placeholder is sent rather than nothing.

Variables

This section is empty.

Functions

func WithDispatchID

func WithDispatchID(ctx context.Context, id string) context.Context

WithDispatchID records the gateway's dispatch fence on ctx.

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client is an a2a-go task store backed by kagent's private TaskStoreService. It keeps no local copy of task state, so every read reflects what the gateway will publish.

func New

func New(cfg Config) (*Client, error)

New dials the kagent API and returns a task store bound to one runtime actor.

The connection is lazy: grpc.NewClient does not connect until the first RPC, so New succeeds even while the controller is starting.

func (*Client) Close

func (c *Client) Close() error

Close releases the gRPC connection.

func (*Client) Create

func (c *Client) Create(ctx context.Context, task *a2a.Task) (sdktaskstore.TaskVersion, error)

Create persists a new task and returns its committed version. The gateway's dispatch fence is attached when present so the send counts as accepted.

func (*Client) Get

func (c *Client) Get(ctx context.Context, taskID a2a.TaskID) (*sdktaskstore.StoredTask, error)

Get loads one stored task.

func (*Client) LastVersion

func (c *Client) LastVersion(id a2a.TaskID) sdktaskstore.TaskVersion

LastVersion returns the most recent committed version recorded for taskID.

func (*Client) List

List returns the session's tasks matching the request.

func (*Client) SessionID

func (c *Client) SessionID(ctx context.Context) (string, error)

SessionID returns the session this client persists under. The value is reread from the identity files on every call because a Substrate restore rebinds them to a new actor.

func (*Client) Settle

func (c *Client) Settle(ctx context.Context, taskID a2a.TaskID, version sdktaskstore.TaskVersion) error

Settle acknowledges that native execution has stopped at the saved version and publishes the task state and history atomically. Without it the gateway keeps a staged boundary private and the caller never sees the final result, so this is the call that makes a completed turn readable.

func (*Client) Update

Update saves the task at the expected version. Optimistic concurrency is enforced server-side, so a stale version surfaces as ErrConcurrentModification.

type Config

type Config struct {
	// Address is the kagent API gRPC address, e.g. "kagent-controller:8083".
	Address string
	// IdentityDir is the Substrate identity directory. Default IdentityDir.
	IdentityDir string
	// SessionID overrides the session ID read from the identity directory. Only
	// tests and offline tooling should set it.
	SessionID string
	// DialOptions are appended to the default dial options.
	DialOptions []grpc.DialOption
}

Config configures a Client.

type DispatchInterceptor

type DispatchInterceptor struct {
	a2asrv.PassthroughCallInterceptor
}

DispatchInterceptor records the gateway's dispatch fence for the turn.

Every save carries the fence so the gateway can prove that the input it reserved a dispatch for was accepted, which is what makes a failed send retryable instead of ambiguous. The fence arrives as a service param on the inbound A2A call and is copied onto the executor context, so Before is the one place that can read it.

func (DispatchInterceptor) Before

Before implements a2asrv.CallInterceptor.

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL