Skip to main content

Message Context

Context objects are structured metadata attached to messages. Context is bidirectional — both the client and the agent may include context objects in their messages.

Some context types reference an artifact_id. These require you to upload an artifact first using the artifact creation endpoint, then reference the resulting ID in your message context. The API specification describes the exact fields required for each context type.

Inspect real contexts

With Developer Mode on, open the ⋮ menu beside a GeoSense message in the FlyPix app and choose Copy Contexts, or right-click a single context chip for Copy Context as JSON. The structure matches what the API exchanges, but the keys are camelCase (artifactId) where the API uses snake_case (artifact_id).

Visibility Context​

The visibility context includes information about what the user can "see" in their current environment. If you have some way of hiding or showing subsections of active vectors to the user, they should be indicated in the visibility context.

Position Context​

The position context indicates to the agent what the user's viewport can display. This can be used to determine locally-relevant information to include in the agent response. The content is simply a bounding box.

Selection Context​

The selection context includes information about objects the user is actively interacting with. It can include any of the main object types in the platform: annotations, regions, and suggestions. If your application does not track ephemeral suggestion objects, leave the suggestions field of the selection context empty.

Suggestion Context​

The suggestion context communicates ephemeral geometry data that exists only within the host application. It is an artifact context: rather than inlining raw geometry, you upload an artifact containing the suggestion list and reference its ID.

The artifact must contain an array of suggestion objects in the following format:

type Suggestion = {
  geometry: string;     // WKB geometry encoded as base64
  confidence?: number;  // optional quality score in [0, 1]
}

If your application supports dynamic, ephemeral user-generated geometries, you can include them by uploading an artifact in this format and referencing it in the suggestion context.

The agent may also send a suggestion context back to the client. This happens when the result of a user query is raw geometry data — for example, when the agent has computed or located geometries that do not yet exist as annotations in any vector layer.

Image Context​

The image context is a way to provide raw image data to the agent. This is generally used alongside capturing a static screenshot of the viewport for the agent to analyze.

Data Context​

Data contexts point to a remote artifact containing machine-readable data. They are primarily sent by the agent to attach structured results to a message, and you should generally not include data contexts in outgoing client messages. For how the agent uses data contexts within tool payloads, see Interactions & Tools.