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

>  Provide either `agentOId` or `experimentOId` depending on what you want to run.
- Use `agentOId` to run a specific agent.
- Use `experimentOId` to run a specific experiment.
Only one of them should be set at a time. 

# Sequence Agent

## Runtime Context & Instructions

The API uses `runtimeContext` and `runtimeInstructions` to pass dynamic per-contact data to your agent at execution time. These are **not** the same fields as the MCP tool schema (which uses `allEmailsContext` / `allEmailsInstructions`).

<Warning>
  If you're migrating from the MCP tool to the direct API, note the schema difference:

  | MCP Tool Field          | API Field                 |
  | ----------------------- | ------------------------- |
  | `allEmailsContext`      | `runtimeContext.all`      |
  | `allEmailsInstructions` | `runtimeInstructions.all` |
  | `step1Context`          | `runtimeContext.1`        |
  | `step1Instructions`     | `runtimeInstructions.1`   |
</Warning>

### How keys work

Both `runtimeContext` and `runtimeInstructions` accept an object where keys control which email steps receive the content:

| Key     | Scope                                  |
| ------- | -------------------------------------- |
| `"all"` | Applied to every email in the sequence |
| `"1"`   | Applied to step 1 only                 |
| `"2"`   | Applied to step 2 only                 |
| `"3"`   | Applied to step 3 only                 |
| `"4"`   | Applied to step 4 only                 |

Step-specific values are **merged** with `"all"` — they don't replace it. Use `"all"` when you have one block of context for the whole sequence (which is the most common case).

### Context vs Instructions

* **`runtimeContext`** — Factual information the agent should draw from: account research, LinkedIn data, recent activity, deal context. Think of this as "what the agent knows about this person."
* **`runtimeInstructions`** — Behavioral directives that steer how the agent writes: tone, length, what to emphasize, what to avoid. Think of this as "how the agent should write."

### Example: Event follow-up with rich context

```json theme={null}
{
  "agentOId": "ca_JxNickJCXUdxFQe2CFKCF",
  "outputFormat": "text",
  "firstName": "Sarah",
  "lastName": "Jackson",
  "companyName": "NICE Ltd",
  "companyDomain": "nice.com",
  "jobTitle": "Strategic Alliance Director",
  "email": "sarah.jackson@nice.com",
  "linkedInProfile": "https://www.linkedin.com/in/sarah-jackson-nice",
  "runtimeContext": {
    "all": "ACCOUNT RESEARCH:\nNICE Ltd expanded their AI partner program from 25 to 200 partners in 18 months. Sarah led the AWS SCA partnership and drove the partner enablement strategy.\n\nEVENT ATTENDANCE:\nAttended Partner Signal Live on 2025-03-15. Participated in the 'Scaling Partner-Led Growth' breakout session.\n\nLINKEDIN CONTEXT:\n12 years in strategic alliances. Previously at Genesys building channel programs. Posts frequently about partner ecosystem strategy."
  },
  "runtimeInstructions": {
    "all": "Keep emails under 150 words. Reference specific details from the event and her LinkedIn background. Use a peer-to-peer tone — she's a senior alliances leader, not a prospect to be pitched.",
    "1": "Lead with a specific detail from the event breakout session she attended. Do not use a generic 'thanks for attending' opener."
  }
}
```

### Example: Simple context (all steps)

If you only need one block of context for the whole sequence, use the `"all"` key:

```json theme={null}
{
  "agentOId": "YOUR_AGENT_OID",
  "firstName": "Alex",
  "lastName": "Chen",
  "companyName": "Datadog",
  "jobTitle": "VP Engineering",
  "email": "alex.chen@datadoghq.com",
  "outputFormat": "text",
  "runtimeContext": {
    "all": "Datadog recently announced a new AI observability product. Alex's team is responsible for the core monitoring platform and has been hiring for ML engineers."
  }
}
```


## OpenAPI

````yaml post /api/v2/agents/sequence/run
openapi: 3.0.0
info:
  version: 1.0.0
  title: Octave API
  description: API for Octave workspace management and AI-powered content generation
servers:
  - url: https://app.octavehq.com
security:
  - ApiKeyAuth: []
paths:
  /api/v2/agents/sequence/run:
    post:
      tags:
        - Agents
      summary: Sequence Agent
      description: Generate Emails for a person
      operationId: runSequenceAgent
      requestBody:
        description: Generate emails input
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  nullable: true
                  description: Email of the person to generate emails for
                  example: john.doe@example.com
                firstName:
                  type: string
                  nullable: true
                  description: First name of the person to generate emails for
                lastName:
                  type: string
                  nullable: true
                jobTitle:
                  type: string
                  nullable: true
                  description: Job title of the person to generate emails for
                companyDomain:
                  type: string
                  nullable: true
                  description: Company domain of the person to generate emails for
                  example: example.com
                companyName:
                  type: string
                  nullable: true
                  description: Company name of the person to generate emails for
                linkedInProfile:
                  type: string
                  nullable: true
                  description: LinkedIn profile of the person to generate emails for
                crmContactId:
                  type: string
                  nullable: true
                crmLeadId:
                  type: string
                  nullable: true
                crmAccountId:
                  type: string
                  nullable: true
                lang:
                  type: string
                  nullable: true
                  description: Language of the person to generate emails for
                requestId:
                  type: string
                  nullable: true
                outputFormat:
                  type: string
                  nullable: true
                  enum:
                    - text
                    - html
                    - markdown
                    - null
                  default: text
                  description: Output format of the emails to generate
                runtimeContext:
                  type: object
                  additionalProperties:
                    type: string
                  description: >-
                    Additional context (facts, research, account data) injected
                    at runtime to personalize the generated sequence. Keys
                    control which email steps receive the context: "all" applies
                    to every email, "1"-"4" apply to a specific step (1-based
                    index). Step-specific context is merged with the "all"
                    context.
                  example:
                    '1': Reference her AWS SCA leadership role in the opening.
                    all: >-
                      Account research: NICE Ltd expanded their AI partner
                      program from 25 to 200 partners. Sarah leads strategic
                      alliances.
                runtimeInstructions:
                  type: object
                  additionalProperties:
                    type: string
                  description: >-
                    Behavioral directives that control how the agent writes the
                    sequence — tone, structure, emphasis, constraints. Keys work
                    the same way as runtimeContext: "all" applies to every
                    email, "1"-"4" apply to a specific step (1-based index). Use
                    runtimeInstructions for writing style directives. Use
                    runtimeContext for factual data.
                  example:
                    '1': >-
                      Lead with a specific personal detail — do not open with a
                      generic intro.
                    all: >-
                      Keep emails under 150 words. Use a consultative tone, not
                      salesy.
                playbookSelectionContext:
                  type: string
                  nullable: true
                  description: >-
                    Playbook selection context of the person to generate emails
                    for
                customContext:
                  type: object
                  nullable: true
                  properties:
                    playbook:
                      type: object
                      properties:
                        oId:
                          type: string
                      required:
                        - oId
                    product:
                      type: object
                      properties:
                        oId:
                          type: string
                      required:
                        - oId
                    service:
                      type: object
                      properties:
                        oId:
                          type: string
                      required:
                        - oId
                    persona:
                      type: object
                      properties:
                        oId:
                          type: string
                      required:
                        - oId
                    segment:
                      type: object
                      properties:
                        oId:
                          type: string
                      required:
                        - oId
                  description: >-
                    Pins specific library entities for this run, overriding the
                    agent's configured selection. Each field takes the oId of an
                    entity in your workspace, and that exact entity is used with
                    no re-matching. On motion agents, playbook.oId must be an
                    active motion playbook; if the agent is configured with a
                    specific motion, the playbook must belong to that motion or
                    the request fails with a 400. product/service pin the
                    offering unless the resolved motion playbook supplies its
                    own (reported as a run warning).
                  example:
                    persona:
                      oId: pe_xxxxxxxxxxxxxxxxxxxxx
                    segment:
                      oId: sg_xxxxxxxxxxxxxxxxxxxxx
                fullSequenceMode:
                  type: boolean
                agentOId:
                  type: string
                  description: >-
                    AgentOId is required when creating an agent in the
                    application. You can find it in the Agents section of your
                    dashboard.
                  example: agent_123
                experimentOId:
                  type: string
                  description: ExperimentOId is required when running an experiment
                  example: experiment_123
                includeFullAnnotation:
                  type: boolean
                  description: >-
                    If true, returns full annotation data including metadata. If
                    false or omitted (default), returns minimal annotations to
                    reduce response size.
      responses:
        '200':
          description: Generate emails successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  _metadata:
                    $ref: '#/components/schemas/Metadata'
                  found:
                    type: boolean
                    description: Whether the operation was successful
                    example: true
                  message:
                    type: string
                    nullable: true
                    description: Message
                    example: Additional information
                  data:
                    $ref: '#/components/schemas/EmailAgentData'
                required:
                  - _metadata
                  - found
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                type: object
                properties:
                  _metadata:
                    $ref: '#/components/schemas/Metadata'
                  message:
                    type: string
                required:
                  - _metadata
                  - message
      deprecated: false
components:
  schemas:
    Metadata:
      type: object
      properties:
        usage:
          type: number
          default: 0
          example: 0
          description: API usage
        requestId:
          type: string
          example: requestId
          description: Request ID
        message:
          type: string
          example: message
          description: Message
        timestamp:
          type: string
          example: '2021-01-01T00:00:00.000Z'
          description: Timestamp
      required:
        - requestId
        - timestamp
    EmailAgentData:
      type: object
      nullable: true
      properties:
        emails:
          type: array
          nullable: true
          items:
            type: object
            properties:
              email:
                type: string
              subject:
                type: string
              coreValueProp:
                type: string
                nullable: true
                default: ''
              sections:
                type: object
                nullable: true
                properties:
                  greeting:
                    type: string
                    nullable: true
                    default: ''
                  opening:
                    type: string
                    nullable: true
                    default: ''
                  body:
                    type: string
                    nullable: true
                    default: ''
                  closing:
                    type: string
                    nullable: true
                    default: ''
                  cta:
                    type: string
                    nullable: true
                    default: ''
                  ps:
                    type: string
                    nullable: true
                    default: ''
                  signature:
                    type: string
                    nullable: true
                    default: ''
              metadata:
                type: object
                nullable: true
                properties:
                  openerPattern:
                    type: string
                  hookTopic:
                    type: string
                  ctaVerb:
                    type: string
                  valuePropsUsed:
                    type: array
                    items:
                      type: string
                  referencesUsed:
                    type: array
                    items:
                      type: string
                required:
                  - openerPattern
                  - hookTopic
                  - ctaVerb
                  - valuePropsUsed
                  - referencesUsed
            required:
              - email
              - subject
        product:
          $ref: '#/components/schemas/LibraryEntitySlot'
        service:
          $ref: '#/components/schemas/LibraryEntitySlot'
        solution:
          $ref: '#/components/schemas/LibraryEntitySlot'
        playbook:
          $ref: '#/components/schemas/LibraryEntitySlot'
        persona:
          $ref: '#/components/schemas/LibraryEntitySlot'
        useCases:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/LibraryEntitySlot'
        referenceCustomers:
          type: array
          nullable: true
          items:
            $ref: '#/components/schemas/LibraryEntitySlot'
        outputType:
          type: string
          nullable: true
          enum:
            - SCOPED_PLAYBOOK
            - BEST_FIT_PLAYBOOK
            - RESEARCH_BASED
            - ALL
            - null
        annotations:
          type: object
          nullable: true
          properties:
            annotations:
              type: array
              nullable: true
              items:
                type: object
                properties:
                  type:
                    type: string
                  meta:
                    nullable: true
                  title:
                    type: string
                  description:
                    type: string
                    nullable: true
                  url:
                    type: string
                    nullable: true
                required:
                  - type
                  - title
            metadata:
              nullable: true
    LibraryEntitySlot:
      type: object
      nullable: true
      properties:
        oId:
          type: string
        name:
          type: string
        description:
          type: string
          nullable: true
        matchConfidence:
          type: string
          nullable: true
          enum:
            - LOW
            - MEDIUM
            - HIGH
            - null
        matchAnalysis:
          type: string
          nullable: true
      required:
        - oId
        - name
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: api_key

````