> ## Documentation Index
> Fetch the complete documentation index at: https://docs.svantic.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Types

# Types

Canonical listing of the configuration and value types exported from `@svantic/sdk`. Individual class pages link back here for option details.

## `AgentConfig`

Passed to `new Agent(...)`. See [Agent](./agent) for methods.

| Field           | Type                                                   | Purpose                                                                                                  |
| --------------- | ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------- |
| `name`          | `string`                                               | Display name in the agent card.                                                                          |
| `description`   | `string`                                               | What the agent does. Shown to callers and LLMs.                                                          |
| `public_url?`   | `string`                                               | Public HTTPS URL. Set this **only** for hosted-mode agents.                                              |
| `port?`         | `number`                                               | Port for `agent.start()` in hosted mode. Ignored in connected mode and for `expose(app)`.                |
| `mesh?`         | `{ svantic_url?, client_id?, client_secret?, token? }` | Svantic platform config. Omit to skip registration. `svantic_url` defaults to `https://api.svantic.com`. |
| `instructions?` | `string`                                               | System prompt for smart agent mode.                                                                      |
| `llm?`          | [`LlmConfig`](#llmconfig)                              | LLM for smart agent mode.                                                                                |
| `version?`      | `string`                                               | Advertised version. Default `'1.0.0'`.                                                                   |
| `agent_type?`   | `string`                                               | Logical type for mesh routing. Defaults to `name`.                                                       |
| `instance_id?`  | `string`                                               | Unique per-process id. Auto-generated from hostname + port/pid if omitted.                               |
| `context?`      | `Record<string, unknown>`                              | Live metadata surfaced on the card.                                                                      |
| `learning?`     | [`LearningConfig`](#learningconfig)                    | Controls platform learner behavior for this agent.                                                       |

## `CapabilityConfig`

Passed to `agent.define_capability(...)`.

| Field         | Type                                    | Purpose                                                  |
| ------------- | --------------------------------------- | -------------------------------------------------------- |
| `name`        | `string`                                | Unique, snake\_case.                                     |
| `description` | `string`                                | Shown to LLMs and remote callers. Invest here.           |
| `parameters`  | [`CapabilitySchema`](#capabilityschema) | JSON Schema for the handler's arguments.                 |
| `tags?`       | `string[]`                              | Free-form labels shown on the agent card.                |
| `handler`     | `(args, context) => Promise<unknown>`   | Async function that runs when the capability is invoked. |

## `CapabilitySchema`

JSON Schema subset used for capability parameters.

```typescript theme={null}
interface CapabilitySchema {
  type: 'object';
  properties: Record<string, SchemaProperty>;
  required?: string[];
}

interface SchemaProperty {
  type: 'string' | 'number' | 'boolean' | 'integer' | 'array' | 'object';
  description?: string;
  enum?: string[];
  default?: unknown;
  items?: SchemaProperty;
  properties?: Record<string, SchemaProperty>;
  required?: string[];
}
```

## `CapabilitySessionContext`

Second argument to every capability handler.

| Field                  | Type                     | Description                                                                      |
| ---------------------- | ------------------------ | -------------------------------------------------------------------------------- |
| `session_id`           | `string`                 | Svantic session id the invocation belongs to.                                    |
| `tenant_id`            | `string`                 | Tenant that owns the session.                                                    |
| `propagation_headers?` | `Record<string, string>` | Raw W3C headers (`traceparent`, `baggage`). Forward to downstream HTTP services. |
| `parent_trace_id?`     | `string`                 | 32-hex trace id parsed from `traceparent`.                                       |
| `parent_span_id?`      | `string`                 | 16-hex span id parsed from `traceparent`.                                        |
| `baggage?`             | `Record<string, string>` | Parsed `baggage`. Empty when absent.                                             |

## `LlmConfig`

| Field          | Type                                  | Description                                                                       |
| -------------- | ------------------------------------- | --------------------------------------------------------------------------------- |
| `provider`     | `'gemini' \| 'openai' \| 'anthropic'` | LLM provider.                                                                     |
| `model?`       | `string`                              | Provider-specific model name. Sensible defaults per provider.                     |
| `api_key?`     | `string`                              | API key. Falls back to `GOOGLE_API_KEY` / `OPENAI_API_KEY` / `ANTHROPIC_API_KEY`. |
| `temperature?` | `number`                              | Sampling temperature.                                                             |
| `max_tokens?`  | `number`                              | Response cap.                                                                     |

## `MeshConnectorConfig`

Passed to `new MeshConnector(agent, config)`. Same fields appear on `AttachConfig.mesh` and (partially) on `AgentConfig.mesh`.

| Field                           | Type                      | Default                   | Purpose                                                                 |
| ------------------------------- | ------------------------- | ------------------------- | ----------------------------------------------------------------------- |
| `svantic_url?`                  | `string`                  | `https://api.svantic.com` | Svantic platform URL.                                                   |
| `client_id?` / `client_secret?` | `string`                  | —                         | Credentials for the OAuth2 `client_credentials` grant.                  |
| `token?`                        | `string`                  | —                         | Pre-issued JWT (skips credential exchange).                             |
| `retries?`                      | `number`                  | `3`                       | Registration retry attempts.                                            |
| `retry_delay_ms?`               | `number`                  | `2000`                    | Delay between retries.                                                  |
| `session_count_provider?`       | `() => number`            | —                         | Reports active-session count on heartbeat.                              |
| `deployment_mode?`              | `'connected' \| 'hosted'` | `connected`               | Transport mode.                                                         |
| `dispatch_auth?`                | `DispatchAuthConfig`      | —                         | Turns on dispatch-auth envelopes. See [Dispatch auth](./dispatch-auth). |

## `LearningConfig`

Platform learner configuration, re-exported from `@svantic/shared`. Use it to opt this agent into (or out of) automated knowledge capture. Fields include `enabled`, `scope`, and capture filters; see the Knowledge Store concept page for semantics.

## `ExecutionContext`

Structured execution context forwarded to the learner. Re-exported from `@svantic/shared`. Set via [`MessageBuilder.with_execution_context()`](./message-builder).

## `FilePayload`

File attachment carried in a message `DataPart`.

| Field                                                | Type     | Description                                                                                                              |
| ---------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------ |
| `name`                                               | `string` | Filename shown to the agent.                                                                                             |
| `mime_type`                                          | `string` | IANA media type.                                                                                                         |
| `size`                                               | `number` | Bytes.                                                                                                                   |
| `file_id?`                                           | `string` | **Preferred.** Id returned by the platform file-upload endpoint. The mesh resolves it to LLM-native format at call time. |
| `content?` / `data?` / `file_uri?` / `artifact_ref?` | `string` | *Deprecated.* Inline-content alternatives, kept for compatibility.                                                       |

## `AgentStatus` / `AgentStatusValue`

```typescript theme={null}
enum AgentStatus {
  AVAILABLE = 'available',
  BUSY      = 'busy',
  DRAINING  = 'draining',
  OFFLINE   = 'offline',
  UNHEALTHY = 'unhealthy',
  UNKNOWN   = 'unknown',
}
```

`AgentStatusValue` is the string-literal union (`'available' | 'busy' | …`). `AGENT_STATUS_VALUES` is the runtime array, handy for Zod enums.

## Response types

Shapes returned by related platform APIs — re-exported so TypeScript consumers don't have to re-declare them. See the API Reference for the REST contracts.

| Type                             | Endpoint                          |
| -------------------------------- | --------------------------------- |
| `McpRegistrationResponse`        | `POST /config/add_mcp_default`    |
| `McpListResponse`                | `POST /config/get_mcp_defaults`   |
| `McpRemoveResponse`              | `POST /config/remove_mcp_default` |
| `GeminiFileResponse`             | `POST /files/upload`              |
| `SessionSummary`                 | `POST /sessions/list`             |
| `SessionHistory` (`SessionTurn`) | `POST /sessions/get`              |
| `ApprovalListResponse`           | `POST /guard/get_approvals`       |

## A2A re-exports

The SDK re-exports A2A primitive types from `@a2a-js/sdk` so you don't import them twice: `AgentCard`, `AgentSkill`, `Message`, `Task`, `TaskState`, `TextPart`, `DataPart`, `FilePart`, `Part`, `TaskStatusUpdateEvent`, `TaskArtifactUpdateEvent`, and the `A2AStreamEventData` union used by streaming APIs.