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
- func WithDispatchID(ctx context.Context, id string) context.Context
- type Client
- func (c *Client) Close() error
- func (c *Client) Create(ctx context.Context, task *a2a.Task) (sdktaskstore.TaskVersion, error)
- func (c *Client) Get(ctx context.Context, taskID a2a.TaskID) (*sdktaskstore.StoredTask, error)
- func (c *Client) LastVersion(id a2a.TaskID) sdktaskstore.TaskVersion
- func (c *Client) List(ctx context.Context, req *a2a.ListTasksRequest) (*a2a.ListTasksResponse, error)
- func (c *Client) SessionID(ctx context.Context) (string, error)
- func (c *Client) Settle(ctx context.Context, taskID a2a.TaskID, version sdktaskstore.TaskVersion) error
- func (c *Client) Update(ctx context.Context, update *sdktaskstore.UpdateRequest) (sdktaskstore.TaskVersion, error)
- type Config
- type DispatchInterceptor
Constants ¶
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.
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.
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 ¶
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 ¶
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) 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 ¶
func (c *Client) List(ctx context.Context, req *a2a.ListTasksRequest) (*a2a.ListTasksResponse, error)
List returns the session's tasks matching the request.
func (*Client) SessionID ¶
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 ¶
func (c *Client) Update(ctx context.Context, update *sdktaskstore.UpdateRequest) (sdktaskstore.TaskVersion, error)
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.