openai/openai-agents-python

Set [RunConfig.output_guardrail_blocked_message][agents.run.RunConfig.output_guardrail_blocked_message] to a non-empty string or a synchronous formatter when your application needs a different data-free placeholder. The formatter receives [OutputGuardrailBlockedMessageArgs][agents.run.OutputGuardrailBlockedMessageArgs] with the SDK default, the guardrail name, the agent, and the active run context. It never receives the rejected tool output or guardrail output_info. The returned text is persisted and replayed wherever the SDK retains the sanitized terminal-tool turn, so keep it free of sensiti

Use synthetic fixtures and obvious placeholder credentials in tests, examples, snapshots, and documentation. Never commit real API keys, tokens, cookies, signing keys, customer data, private prompts or responses, tool payloads, or recordings.

Continue authorized local work through fixes, applicable review, verification, and handoff. Stop for a concrete unresolved contract or scope decision, missing authority, or an external blocker. When a skill causes a stop, identify the exact instruction and explain the missing decision; do not ask for a generic continuation prompt. Never push, open a PR, or otherwise mutate GitHub.

$pr-draft-summary: After applicable review and verification, generate the local PR draft for runtime, tests, examples, build/test changes, or behavior-impacting docs, including uncommitted work. Skip repo-meta/editorial-only work, an explicit user opt-out, or the release-specific handoff below. A draft never authorizes a branch, commit, push, or PR creation.

CI permissions: Keep untrusted contributor code and artifacts away from secrets and privileged execution. Use explicit least-privilege workflow/job permissions and full-SHA action pins. Review changes involving pull_request_target, artifact consumption, shell interpolation, write tokens, or OIDC credentials. Never disable security checks, secret protections, or required review to obtain a passing result.

Secrets and fixtures: Use synthetic data and placeholder credentials. Never place real credentials, customer data, private prompts or responses, tool payloads, or recordings in code, tests, snapshots, logs, documentation, or shared artifacts. Use approved credential injection only for explicitly authorized live tests; do not expose credentials to untrusted code or browser clients.

Server-managed conversations (conversation_id, previous_response_id, or auto_previous_response_id) do not support handoff input filters; use a separate run with explicitly selected input when the receiving agent must not inherit that server-managed history. Do not reuse the original conversation_id or previous_response_id in that separate run.

Adapt the shared application policy to these callbacks instead of maintaining separate capability lists. The callbacks control which capabilities the SDK exposes for the current run; they cannot authorize a model-generated argument or resource selection. For function tools, enforce those decisions inside the tool implementation or with tool input guardrails and approvals when appropriate. MCP servers must authorize their own protected operations. For a handoff with input_type, check the parsed input at the start of on_handoff, before application side effects, and raise instead of returning whe

When you pass an explicit client to [OpenAIProvider][agents.models.openai_provider.OpenAIProvider], that client owns its connection and account settings. Do not also pass api_key, base_url, websocket_base_url, organization, or project to OpenAIProvider; combining openai_client with any of those arguments raises [UserError][agents.exceptions.UserError] instead of silently ignoring the duplicate value. Set the intended values when constructing AsyncOpenAI.

Within a single run, derived wrappers share the same underlying app context, approval state, and usage tracking. Nested [Agent.as_tool()][agents.agent.Agent.as_tool] runs may attach a different tool_input, but they do not get an isolated copy of your app state by default.

clone() uses dataclasses.replace, so it performs a shallow copy. A list attribute that you do not override, such as tools, handoffs, mcp_servers, input_guardrails, or output_guardrails, remains the exact list held by the original agent. Mutating that list through either agent therefore affects both agents. To give the clone an independent list container, pass a new list, for example pirate_agent.clone(tools=[*pirate_agent.tools, extra_tool]). The entries copied into that new list remain the same tool or handoff objects unless you replace those entries too.

Provide credentials for explicitly authorized live tests through the approved environment or secret store. Use the minimum necessary access and keep live credentials out of untrusted contributor runs. Do not embed credentials in browser code, commands, URLs, or generated artifacts.

Inspect diffs and attachments for sensitive data before sharing them. Include logs, exceptions and their chained context, tracebacks, telemetry, session exports, files, and audio in that check. Do not assume a tracing redaction setting sanitizes every channel.

When declining a request, name the unmet criterion and the evidence that would support reconsideration. Do not speculate about the contributor's motives or equate a small project with poor quality. For example:

Existing entries may remain while maintainers review them as concerns arise; this policy does not require a bulk removal or certify the current list. A broken setup guide, unavailable release, discontinued tracing support, or misleading claim warrants review. Give the integration maintainer an opportunity to correct ordinary documentation or maintenance problems. Remove entries when those problems remain unresolved, and remove unsafe or deceptive links promptly. Follow the private reporting process in SECURITY.md for undisclosed vulnerabilities. Routine link repairs do not require a new adopti

Keep an accepted listing to a neutral product name and a direct integration-guide link. Do not add promotional copy, tracking or referral links, SDK dependencies, or integration implementation code as part of a listing request.

Review the submitted evidence against each criterion and record the concrete basis for acceptance or the missing evidence in the issue. Check that the guide and published release describe the same integration. Distinguish a vendor's claim, inspected tests, and independently observed results. Do not run downloaded integration code with credentials or sensitive data merely to assess a listing.

Open an issue before preparing a listing change. Include the integration name, your affiliation, the published package and version, the direct setup guide, compatibility evidence, independent-use evidence, and the maintainer/support link. Share only evidence you have permission to disclose. Do not post customer identities without consent, private usage data, credentials, prompts, responses, or recordings. If independent-use evidence cannot be shared safely, explain the limitation; it remains unverified until maintainers can assess suitable evidence.

Stars, download counts, funding, paid promotion, and inclusion in other directories do not substitute for these criteria. Meeting the criteria makes a request eligible for review, not guaranteed acceptance; maintainers should explain any remaining relevance or evidence concern.

Independent use. Provide at least one independently verifiable example of continued use of this integration with the Agents SDK by a user or project outside the integration maintainer's organization. Evidence can be a maintained public application, an independent technical write-up, or a concrete usage report from an unaffiliated user describing the workflow and experience over time. Vendor demos, launch announcements, customer logos, and adoption of a different framework integration do not satisfy this criterion. Small projects can qualify; production scale is not required.

Pull requests are limited to repository collaborators. We do not accept pull requests from non-collaborators, including documentation or example changes. If you are not a collaborator, please open an issue instead of preparing a pull request. Include the affected version, expected and actual behavior, and a small, sanitized reproduction when applicable.

When a feature or bug fix introduces behavior that is not yet available in the latest published release, do not include docs/ changes that describe that unreleased behavior in the feature or bug-fix pull request, and do not expect those changes as part of that pull request. Handle them in a separate docs-only pull request so maintainers can coordinate its merge timing with the release that makes the documentation accurate. This exception applies only when the documentation would be incorrect for the latest published release; documentation that is already accurate for released behavior remains

Work in the user's current checkout and on the current branch by default. If the Codex task is already running in a selected Git worktree, use that worktree without requesting additional permission. Do not create or switch to another Git worktree, and do not create or switch branches, unless the user explicitly asks for or approves that exact action in the current conversation. A request to implement, investigate, review, test, or verify changes does not by itself authorize changing the active worktree or branch.

Use RUNNING only in commentary while autonomous work remains and no user action is required. Do not end a turn with a final response that says the task is still running or asks the user to send a generic continuation prompt.

$openai-knowledge: Use when OpenAI API/platform behavior needs authoritative external evidence. Inspect local code for SDK-owned behavior; do not repeat unchanged external research for purely local implementation details.

Repository skills are stored under .agents/skills/. References below authorize their use when the stated condition applies; no separate manual invocation is needed unless explicitly required. Read the selected SKILL.md, then only the supporting references needed for its route. User instructions and already-approved scope take precedence over skill defaults, subject to applicable permissions. Do not repeat an approval already given for local implementation, review, or verification.

Findings and exceptions: Escalate critical or actively exploited findings privately without delay. Do not publish an undisclosed reproduction, patch, or sensitive finding in an issue, pull request, or review request before disclosure is coordinated. Stop propagating exposed credentials and have their owner revoke or rotate them. Record proposed exceptions with an owner, mitigation, approval, and expiry; do not treat proposals or unknown facts as accepted risk.

Evidence and handoff: Report the security-sensitive paths reviewed, relevant checks and results, and unresolved gaps. Distinguish requirements from verified controls: unavailable alert APIs are not evidence of zero alerts, a configured publisher is not proof of registry binding or provenance, and a completed scan does not clear its findings. Documentation edits alone do not establish repository-wide compliance.