> ## Documentation Index > Fetch the complete documentation index at: https://docs.roark.ai/llms.txt > Use this file to discover all available pages before exploring further. # Guide a running setup > Tells a running setup what to focus on or avoid, in your own words. It reads it on its next turn and it outranks setup's own plan. Refused once setup has finished. ## OpenAPI ````yaml /api-reference/openapi.documented.json post /v1/agent/{agentId}/setup/{setupId}/guidance openapi: 3.1.0 info: title: Roark Analytics API description: >- The Roark Analytics API gives you access to the same API that powers the award winning Roark Analytics platform. version: 1.0.0 servers: - description: Production url: https://api.roark.ai security: - Bearer: [] tags: - name: Agent - name: Customer - name: Agent Endpoint - name: Tool - name: Phone Number - name: Call - name: Chat - name: Conversation - name: Metric - name: Metric Policy - name: Metric Collection Job - name: Customer Flow - name: Customer Flow Edge Case - name: Simulation - name: Simulation Persona - name: Simulation Environment - name: Simulation Scenario - name: Simulation Run Plan - name: Simulation Template - name: Simulation Audio Clip - name: Simulation Run Plan Job - name: Simulation Job - name: HTTP Request Definition - name: Webhook - name: Issue - name: Autoimprove - name: Agent Config - name: Knowledge Base - name: Calendar Integration - name: MCP Server Integration - name: Config - name: Organization Project - name: Organization Project Member - name: Organization Project API Key - name: Organization Config - name: CLI Auth - name: Me - name: Project - name: Usage - name: Analytics - name: Dashboard - name: Live Report - name: Benchmark - name: Health - name: Campaign Credit paths: /v1/agent/{agentId}/setup/{setupId}/guidance: post: tags: - Agent summary: Guide a running setup description: >- Tells a running setup what to focus on or avoid, in your own words. It reads it on its next turn and it outranks setup's own plan. Refused once setup has finished. operationId: postV1AgentByAgentIdSetupBySetupIdGuidance parameters: - in: path name: agentId schema: type: string format: uuid required: true - in: path name: setupId schema: type: string format: uuid required: true requestBody: content: application/json: schema: $ref: '#/components/schemas/AgentSetupMessageInput' responses: '202': description: Setup will read it on its next turn content: application/json: schema: type: object properties: data: $ref: '#/components/schemas/AgentSetup' required: - data '400': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Validation error example: type: validation code: invalid_parameter message: The request was invalid param: email description: Bad Request '401': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Authentication error example: type: authentication code: unauthorized message: Authentication required description: Unauthorized '403': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Permission error example: type: forbidden code: permission_denied message: You do not have permission to access this resource description: Forbidden '404': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Not found error example: type: not_found code: resource_not_found message: The requested resource could not be found description: Not Found '409': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Conflict error example: type: conflict code: resource_in_use message: The resource is in use and cannot be deleted description: Conflict '500': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Server error example: type: internal code: internal_error message: Internal server error description: Internal Server Error x-codeSamples: - lang: JavaScript source: >- import Roark from '@roarkanalytics/sdk'; const client = new Roark({ bearerToken: process.env['ROARK_API_BEARER_TOKEN'], // This is the default and can be omitted }); const response = await client.agentSetup.sendGuidance('182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', { agentId: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e', text: 'x', }); console.log(response.data); - lang: Python source: |- import os from roark_analytics import Roark client = Roark( bearer_token=os.environ.get("ROARK_API_BEARER_TOKEN"), # This is the default and can be omitted ) response = client.agent_setup.send_guidance( setup_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", agent_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e", text="x", ) print(response.data) components: schemas: AgentSetupMessageInput: type: object properties: text: type: string minLength: 1 maxLength: 4000 description: What you want setup to know required: - text AgentSetup: type: object properties: id: type: string format: uuid description: Setup ID agentId: type: string format: uuid status: type: string enum: - PENDING - RUNNING - NEEDS_INPUT - COMPLETED - FAILED - CANCELLED description: >- PENDING, RUNNING, NEEDS_INPUT (waiting on a question; it goes ahead with the default if nobody answers), COMPLETED, FAILED or CANCELLED layers: type: array items: $ref: '#/components/schemas/AgentSetupLayer' description: The checklist setup works through question: $ref: '#/components/schemas/AgentSetupQuestion' activity: type: array items: $ref: '#/components/schemas/AgentSetupActivity' description: What setup did and said, in order industry: type: - string - 'null' enum: - HEALTHCARE - FINANCIAL_SERVICES - INSURANCE - DEBT_COLLECTION - RETAIL - TRAVEL_AND_HOSPITALITY - TELECOMMUNICATIONS - TECHNOLOGY - PUBLIC_SECTOR - UTILITIES - LOGISTICS - AUTOMOTIVE - HOME_SERVICES - RESTAURANTS - EDUCATION - OTHER capabilities: type: array items: type: string enum: - APPOINTMENT_BOOKING - FAQ - IDENTITY_VERIFICATION - ACCOUNT_MANAGEMENT - BILLING_AND_PAYMENTS - ORDER_MANAGEMENT - TROUBLESHOOTING - CALL_ROUTING - LEAD_QUALIFICATION - COLLECTIONS - OUTBOUND_CALLING runPlanId: type: - string - 'null' format: uuid description: The run plan to start once setup completes explore: type: object properties: enabled: type: boolean maxConversations: type: integer maxConversationMinutes: type: integer conversationsUsed: type: integer required: - enabled - maxConversations - maxConversationMinutes - conversationsUsed testDataNeeded: type: array items: type: object properties: label: type: string reason: type: string callId: type: - string - 'null' format: uuid required: - label - reason - callId description: Test data the agent asked for that Roark did not have errorMessage: type: - string - 'null' items: type: array items: $ref: '#/components/schemas/AgentSetupItem' createdAt: type: string completedAt: type: - string - 'null' required: - id - agentId - status - layers - question - activity - industry - capabilities - runPlanId - explore - testDataNeeded - errorMessage - items - createdAt - completedAt description: The tests Roark generated for an agent, and why ErrorResponse: type: object properties: type: type: string enum: - validation - authentication - forbidden - not_found - conflict - payment_required - rate_limit - internal description: The error type category examples: - validation - authentication code: type: string description: Machine-readable error code identifier examples: - invalid_parameter - missing_required_field - unauthorized message: type: string description: Human-readable error message examples: - The request was invalid - Authentication required param: type: string description: The parameter that caused the error (if applicable) examples: - email - user_id details: description: Additional error context information required: - type - code - message AgentSetupLayer: type: object properties: layer: type: string enum: - CORE - INDUSTRY - CAPABILITY - AGENT_CONTEXT - EXPLORATION - CUSTOMER_INSTRUCTIONS status: type: string enum: - COVERED - SKIPPED - OPEN - NOT_APPLICABLE description: >- COVERED: tests exist for it, or are added when setup finishes. SKIPPED: setup could not test it and said why. OPEN: not covered yet; setup does not finish while a layer is open. NOT_APPLICABLE: nothing to test it from. summary: type: string required: - layer - status - summary description: Where one part of testing the agent stands AgentSetupQuestion: type: - object - 'null' properties: question: type: string options: type: array items: type: string defaultOption: type: string required: - question - options - defaultOption description: The question setup is waiting on, while NEEDS_INPUT AgentSetupActivity: type: object properties: kind: type: string enum: - STATUS - REASONING - ACTION - GUIDANCE - QUESTION - ANSWER - EXPLORATION - ERROR description: >- STATUS, REASONING, ACTION, GUIDANCE, QUESTION, ANSWER, EXPLORATION or ERROR text: type: string createdAt: type: string required: - kind - text - createdAt description: One thing setup did or said, in order AgentSetupItem: type: object properties: id: type: string format: uuid layer: type: string enum: - CORE - INDUSTRY - CAPABILITY - AGENT_CONTEXT - EXPLORATION - CUSTOMER_INSTRUCTIONS description: >- Why it exists: CORE (every agent), INDUSTRY, CAPABILITY, AGENT_CONTEXT (your prompt or website), EXPLORATION or CUSTOMER_INSTRUCTIONS kind: type: string enum: - FLOW - METRIC - CHECK - LAYER description: A flow, a metric, or a pass or fail check action: type: string enum: - CREATED - SKIPPED description: CREATED, or SKIPPED with the reason resourceId: type: - string - 'null' format: uuid description: The flow or metric it created label: type: string capability: type: - string - 'null' enum: - APPOINTMENT_BOOKING - FAQ - IDENTITY_VERIFICATION - ACCOUNT_MANAGEMENT - BILLING_AND_PAYMENTS - ORDER_MANAGEMENT - TROUBLESHOOTING - CALL_ROUTING - LEAD_QUALIFICATION - COLLECTIONS - OUTBOUND_CALLING source: $ref: '#/components/schemas/AgentSetupItemSource' reason: type: string origin: type: - string - 'null' enum: - DISCOVERED - INFERRED description: >- Exploration only: DISCOVERED on a call, or INFERRED from a path the agent offered required: - id - layer - kind - action - resourceId - label - capability - source - reason - origin description: Something setup created or chose to leave out, and why AgentSetupItemSource: type: object properties: type: type: string enum: - CATALOGUE - PROMPT - DESCRIPTION - WEBSITE - EXPLORATION_CALL - INSTRUCTIONS url: type: - string - 'null' description: The page it came from, for website sources callId: type: - string - 'null' format: uuid description: The exploration call it came from offsetMs: type: - integer - 'null' description: Where in the call quote: type: - string - 'null' description: The words in the source that led to it required: - type - url - callId - offsetMs - quote securitySchemes: Bearer: type: http scheme: bearer bearerFormat: JWT ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.