OpenAI Agents SDK inside Samora

SAM-ACT-001 / architecture decision

The proposed system

What happens. A Samora API creates a durable goal. Temporal runs the goal and its subject lifecycles. When judgment is needed, a Temporal activity calls a private Python service that uses the OpenAI Agents SDK for one bounded turn. The service returns a typed proposal. Samora policy checks it and writes durable work. Existing Samora services execute the action and emit results that wake the goal again.

Why. The Agents SDK provides the model loop, function tools, specialist agents, handoffs, guardrails, structured output, tracing, and approval interruption state. It does not provide Samora's product database, tenant authorization, provider adapters, day-scale timers, event correlation, duplicate-action protection, or business completion rules.

Scope, non-goals, and design rules

What happens. The first release supports high-level chat goals over typed Samora resources. It can inspect, propose, coordinate, wait, ask for approval, and invoke approved product actions.

Non-negotiable rules

One request under the hood

What happens. The chat looks continuous to the user. Underneath, it is a series of transactions, workflow activations, short agent runs, Samora commands, and durable waits.

User-visible stream, without exposing hidden reasoning

What the current code already provides

What happens today. Samora already owns most execution paths. The implementation should wrap these paths as governed capabilities rather than reimplement them in the SDK runtime.

Target architecture

What happens. Requests cross five trust zones. Each zone has one owner and a small contract. The model has no path around the policy and execution zones.

One owner for each responsibility

What happens. Components can cooperate, but they do not share authority. The matrix below prevents the common failure where the SDK, Temporal, and the database all appear to own the same state.

In simple terms: if two components could both claim to be right, narrow their jobs until only one owns the answer.

Map OpenAI Agents SDK features to Samora

What happens. Samora uses SDK features only inside a decision request. Each feature gets a narrow meaning and an explicit limit.

Agent topology

What happens. One manager owns the final proposal for a decision turn. It may call a few specialists as tools. Deterministic services still perform policy and execution.

Context and memory contract

What happens. The context builder creates two objects. ModelContext contains redacted facts the model may see. RuntimeContext contains authenticated IDs, clients, and policy handles that code needs but the model must not see.

ModelContext {
  objective
  goal_revision
  subject: { type, id_alias, current_version, safe_summary }
  recent_events[]: { type, occurred_at, safe_payload, evidence_ref }
  relevant_history[]
  open_work_summary[]
  active_waits[]
  human_directives[]
  capability_descriptions[]
  business_constraints[]
  decision_schema
}

RuntimeContext {
  workspace_id
  actor_id
  goal_id
  subject_run_id
  decision_turn_id
  temporal_workflow_id
  trace_id
  authenticated_service_clients
  policy_handle
  cancellation_handle
}

Assembly order

1. Read the current goal revision and subject run under the workspace boundary.
2. Resolve current subject versions and relevant domain facts.
3. Read only events after the last accepted decision plus a compact prior summary.
4. Add open work, active waits, approvals, conflicts, and budgets.
5. Resolve the capability snapshot for this actor, goal, and subject.
6. Apply field allowlists, redaction, sensitivity labels, and token budgets.
7. Write a content hash and source references before the SDK call.

Memory layers

Capability registry and tool gateway

What happens. Samora converts internal service methods into versioned capability descriptors. The SDK sees only capabilities allowed for the current actor and subject. Read tools may execute during reasoning. Mutating tools submit proposals that become durable work after policy checks.

Why. A function schema tells the model how to call something. It does not prove the user is authorized, the resource is current, the provider is healthy, or the action is safe to retry.

CapabilityDescriptor {
  capability_id: "agents.update_channel_instructions"
  version: 3
  subject_types: ["agent"]
  description: "Replace instructions for one configured channel"
  input_schema: JSONSchema
  result_schema: JSONSchema
  effect_class: "mutate"          // read | draft | send | mutate | launch | handoff
  required_permissions: ["agents.write"]
  approval_mode: "policy"         // never | policy | always
  handler: "agent-service"
  timeout_ms: 5000
  retry_class: "safe_before_commit"
  conflict_key_recipe: "agent:{id}:channel:{channel}"
  idempotency_key_recipe: "SHA256(workspace_id + ':' + work_item_id + ':' + action_revision)"
  sensitive_fields: ["instructions"]
  enabled_channels: ["voice", "whatsapp", "email", "chat", "sms"]
}

Initial capability families

Persistent data model

What happens. A new agentic schema records control-plane facts. It references existing Samora resource IDs rather than copying channel, agent, campaign, or conversation data.

Why. Goal state and agent-turn state do not fit the current contact-only workflow tables. A separate schema makes the authority and migration boundary clear.

SubjectRef {
  type: "contact" | "opportunity" | "conversation" | "campaign" |
        "workflow_definition" | "workflow_execution" | "agent" |
        "tool" | "knowledge_document" | "integration" | "human_queue" |
        "report_job" | "workspace_operation"
  id: UUID
  expected_version?: string
  parent?: SubjectRef
}

Service and wire contracts

What happens. Go services and the Python runtime communicate through versioned JSON contracts. The Python SDK types use Pydantic. Go mirrors the same JSON Schema. Contract tests stop either side from drifting.

Public goal API, proposed

Private agent runtime API, proposed

AgentRunRequest {
  api_version: "2026-09-04"
  run_id: UUID
  workspace_id: UUID
  actor: { id, role_version }
  goal: { id, revision, objective }
  subject_run: { id, subject_ref, version }
  trigger: { event_id, type }
  model_context: ModelContext
  capability_snapshot: { id, version, capabilities[] }
  limits: { max_turns, wall_clock_ms, output_tokens, tool_calls, cost_microunits }
  correlation: { temporal_workflow_id, temporal_run_id, trace_id }
  resume_state_ref?: opaque_reference
}

AgentRunResult {
  api_version: "2026-09-04"
  run_id: UUID
  status: "completed" | "paused_for_approval" | "failed"
  proposal?: DecisionProposal
  tool_observations[]
  interruptions[]
  resume_state_ref?: opaque_reference
  last_agent?: string
  usage: { input_tokens, output_tokens, tool_calls, estimated_cost_microunits }
  trace_id: string
  error?: { kind, retryable, provider_code, safe_message }
}

Event envelope

GoalEvent {
  event_id: UUID
  workspace_id: UUID
  type: string
  source: "samora" | "provider" | "temporal" | "human" | "timer"
  external_event_id?: string
  goal_id?: UUID
  subject_refs[]
  work_item_id?: UUID
  attempt_id?: UUID
  correlation_id: string
  causation_id?: string
  occurred_at: timestamp
  received_at: timestamp
  safe_payload: object
}

End-to-end runtime sequences

See every database change: play the 52-step transaction trace. It shows the function, reads, staged writes, commit, outbox delivery, approval pause, existing campaign retry, external result, and goal resolution row by row.

A normal decision and action

An approval pause

Default behavior is to end the SDK turn, persist the proposal, and start a fresh turn after approval when more reasoning is needed. Use SDK interruption state only when the exact paused tool call must resume. Store that state encrypted and link it to the Samora approval row.

Waiting and reactivation

What happens. A subject workflow registers a wait with one or more event predicates and an optional deadline. Temporal waits for a signal or timer. The event ledger stays authoritative even if a signal is delayed or duplicated.

Delivery order

1. Validate the event source and workspace.
2. Write or confirm the authoritative domain result.
3. Insert the normalized event with a unique source key.
4. Commit an outbox entry in the same transaction.
5. Publish the Temporal signal.
6. Mark outbox delivery. Reconcile pending rows after crashes.
7. Let the workflow consume the event by ID and record the resulting decision turn.

Concurrency, versioning, and repeat protection

What happens. Thousands of subject runs may progress at once, but each conflicting action is serialized by a key and checked against the latest resource version.

idempotency_key = SHA256(
  workspace_id + ":" +
  work_item_id + ":" +
  action_revision
)

// Every retry of the same logical action reuses this key.
// A changed target or payload requires a new action_revision.

Approval and human work

What happens. Policy may convert a proposal into a human request. The request blocks only dependent work. Other safe subject runs continue.

The approval message must show

• What will change and which resource version is targeted.
• Why Samora proposes it and which evidence supports it.
• External effects, recipients, cost, reversibility, and expected result.
• The exact choices, expiry, and people allowed to decide.
• What work waits and what work continues.
• How to undo the change when an honest rollback exists.

In simple terms: "approve" never means "let the model do whatever it thinks is related." It approves one named action.

Security and policy boundary

What happens. The system filters context before the model call and rechecks every proposed action in fixed code. The tool gateway uses service credentials scoped to known internal APIs. Provider credentials stay with the owning service.

Failure and recovery semantics

What happens. Every failure receives a class, retry owner, safe message, and next state. A transport retry does not become a second business action.

Recovery after deployment

1. Temporal replays workflow code against its history.
2. Activities read current Postgres records using stored IDs and versions.
3. Expired leases return work to the queue.
4. Outbox reconciliation resends missing wake signals.
5. Unknown attempts reconcile before retry.
6. An incompatible SDK continuation checkpoint falls back to a new bounded turn built from canonical facts.

Audit, traces, evaluation, and cost

What happens. Every layer emits its own evidence under the same correlation IDs. Operators can trace a user message to a goal revision, decision, policy result, work item, domain mutation, provider receipt, and completion assessment.

Evaluation suites

OpenAI SDK tracing is useful for model and tool diagnostics. Samora stores the durable audit itself because trace retention, access, and product semantics are different concerns.

Deployment shape

What happens. The new agent runtime deploys as a private stateless service beside existing backend and workflow workers. It can scale by concurrent decision turns. It has no public tool endpoint.

Recommended language

Proposed code placement

In simple terms: these are proposed locations, not files created by this documentation session.

Phased implementation plan

What happens. Build the control plane in slices. Each phase has a safe rollback to existing Samora behavior. Do not start with unrestricted tools or multi-agent complexity.

Feature flags and rollback

• agentic_goals_enabled controls goal creation per workspace.
• agentic_capability_allowlist enables each capability separately.
• agentic_side_effects_enabled defaults off outside test workspaces.
• A goal pins its runtime, prompt, model, capability, and policy versions.
• Rollback disables new goal intake, lets safe in-flight actions settle, pauses remaining runs, and leaves existing non-agentic workflows untouched.
• Schema rollback is additive. Do not drop audit rows. Retire readers only after retention and export requirements pass.

Acceptance tests and release gates

What happens. The system proves durable behavior and safety before broadening tool access. Prompt quality alone is not enough.

Release invariants

Evidence and source boundaries

What happens. This specification combines verified local source with current official OpenAI documentation. Product behavior claims cite local files. SDK behavior claims cite OpenAI Docs.

Official OpenAI Docs

• Agents overview
• Agents SDK quickstart
• Agent definitions
• Running agents
• Orchestration and handoffs
• Guardrails and human review
• Results and next-turn state
• Integrations and observability
• Using tools
• MCP and connectors
• Structured Outputs
• API errors
• Rate limits

Primary local source

• samora-workflows/README.md
• samora-workflows/internal/workflows/contact.go
• samora-workflows/internal/activities/activities.go
• samora-be/database/schemas/workflows.sql
• samora-be/services/agent_service/
• samora-be/services/tools_service/
• samora-be/services/kbase_service/
• samora-be/services/integrations_service/
• samora-be/services/human_operations_service/
• samora-be/services/realtime_service/broker.go
• samora-be/clients/llm/gateway.go
• samora-dispatcher/internal/store/jobs.go

Session decision record

Mandatory understanding quiz

Status: not accepted. Score: 0/8 pending. A passing score is 7/8.

Reply with answers numbered 1 through 8. The task remains open until the answers pass.